Contributing to TOVIO

The engine, CLI, bindings, SDKs, edges, and the specification are Apache-2.0 and open to contribution. The Forge and the commercial components are not.

Before you write code

• Read the contributing guide and the code of conduct in the repository, and the documentation map — it explains how the specifications, decision records, and architecture documents fit together, and reading it first saves rework.
• A Contributor Licence Agreement is required, and it is merge-blocking. See below.
• For anything architectural, expect a decision record to come first. Significant or hard-to-reverse choices are written down and decided before they are implemented, and an accepted record is superseded by a new one rather than quietly edited.

The CLA, concretely

TOVIO uses a Contributor Licence Agreement rather than a bare developer certificate of origin, because of the per-component licensing: the project ships a commercial Forge and enterprise tier alongside the Apache-2.0 engine, which requires it to hold the rights to sublicense and relicense contributions.

It does not take your rights away. You keep the copyright in your contribution; the agreement grants the project a broad licence, including the right to distribute your work under both the Apache-2.0 and the commercial terms.

The ceremony is in-repo, with no third-party service: first-time contributors add themselves to a versioned roster in the same pull request as their first contribution, quoting the acceptance sentence from the agreement text in that commit's message. A merge-blocking check fails any pull request containing a commit whose author is not on the roster, and validates the roster itself on every run. Contributions to the specification and the conformance corpus are covered by the same agreement. Corporate agreements for employer-owned work are arranged with the maintainers before you submit.

On top of that, sign off every commit with a real name and email matching your author identity.

The code of conduct

The project uses the Contributor Covenant, with enforcement reports going to conduct@tovio.dev. It applies across every project space — repositories and their reviews and discussions, the feedback portal and its boards, the documentation site, any named chat or mailing list, and project events. A suspected vulnerability is never a conduct report and never belongs in a community space; it goes through the security route below.

Conventions review will hold you to

• The core library performs no I/O. No filesystem, no network, no environment, no terminal, no config reading, no ambient clock or randomness — storage, time, randomness, signing, and the Key Authority are all injected by the caller. A change that adds I/O to the core is wrong by construction; push the I/O up into the CLI, the Forge, or the keystore wrapper. This is what keeps the engine deterministic and testable with pure in-memory inputs, and it is not negotiable.
• Serialisation stays canonical. A non-deterministic encoding breaks content addressing, so it is a correctness defect rather than a style preference.
• Every new user-visible error needs a catalog entry with a stable TVO-AREA-NNN code and a remediation, rendered in three parts: what happened, why, and what to do next. The error type in the core is structured; the rendering is the wrapper's job. A lint fails the build on any constructed error without a catalog entry.
• Secrets are zeroized and never leak. Key material is wrapped in a zeroizing type and must never reach the object store, the wire, logs, or the operation log. A lint enforces this too.
• Cite the requirement IDs and decision records your code implements, in doc comments or test names, and in the commit message and pull-request description. An uncovered normative requirement shows up as a visible gap in the traceability view, which is the point.
• The command surface is governed: to add a top-level command you must remove or merge one. New functionality usually belongs as a subcommand or a flag on an existing command. Destructive commands require a spelled-out confirmation gate, not a bare yes flag.
• Edges call the engine through the bindings and never reimplement hashing, encoding, or crypto in TypeScript.

What must pass before you open a pull request

The same gates continuous integration runs: formatting, the linter with warnings treated as errors, the full test suite, and the conformance corpus at 100 percent or fail — plus the TypeScript lint and tests if you touched an edge. On top of those, integration enforces a determinism gate, cryptographic known-answer and negative suites, a fuzz-corpus smoke replay, and lints for secrets in the object store, error-catalog completeness, and requirement coverage. Failures in the highest-priority classes — data integrity, determinism, cryptographic safety, no data loss — block merge unconditionally.

Fixing a defect in one of those properties? The regression test that fails without your fix lands before the fix does. If you change conformance-affecting behaviour, the corpus changes in the same pull request.

Every pull request needs at least one maintainer review and green integration. Changes touching cryptography, the storage format, enforcement, or the audit chain get extra scrutiny and may need a second reviewer. Keep it to one logical change per pull request.

Good first contributions

Documentation, error-message quality, and platform testing. Error quality in particular is treated as a first-class product requirement rather than polish, so improving a confusing message is a real contribution and reviewers treat it as one.

Never through a public channel: security

Anything that could expose protected content, leak a secret, forge a signature, or bypass an enforcement stage does not go in a public issue, pull request, or discussion. Send it to security@tovio.dev, the address also named at the project's security.txt location.

The project states the current intake honestly rather than implying more: until a PGP key or the repository's private vulnerability reporting is published, reports travel over ordinary email. Keep proof-of-concept material minimal and never include live secrets, production credentials, or anyone else's protected content. The public feedback portal is not a security channel — a vulnerability posted there is taken down without a public reply and the author is contacted privately with this route.

Before reporting, it is worth checking the threat model's documented residual risks: several Tier-1 limitations are deliberate and openly recorded, so you can tell an intended tradeoff from a bug.