Browse documentation
Docs target stable release v0.9.1.Stable vs main checked 2026-10-09

Portable .tine v2

The normative format specification and its 523 conformance vectors cover portable v2, repository v3, packs, and signatures. v2 orders keys by code point; v3 uses UTF-16 code units. Attestation signatures use the v2 canonicalizer over a v3 object.

A .tine v2 artifact stores a content-addressed directed graph plus transcript, cache, manifest, policy metadata, integrity data, and optional signature information.

artifact.py
1from opentine import Run
2
3integrity = Run.verify_integrity("result.tine")
4print(integrity.ok, integrity.reason, integrity.draft)
5
6run = Run.load("result.tine")
7
8run.save("copy.tine")

Step identity

Step IDs are full SHA-256 hashes over canonical immutable payloads: parent links, kind, inputs, outputs, model or tool metadata, and errors. Run.steps remains a stable traversal view while the artifact stores graph ancestry through parent_ids, named refs, and branch metadata.

Provider provenance

Since opentine 0.8, model steps record an opaque provider field beside model and usage. Verify, fork, diff, and replay do not branch on it. The field is additive: older artifacts load with an empty provider and re-serialize byte-identically, so portable storage remains v2.

Fork-act identity

Content-addressed step IDs describe retained graph content. Since opentine 0.4, a default portable fork's run ID separately describes the fork act: source lineage, retained slice, fork point, branch, declared intent, and a recorded nonce. This lets two interventions from the same step remain independently addressable. Cached replay deliberately opts into deterministic identity.

Integrity and signatures

The checksum covers the artifact body but excludes metadata. New signatures use thetine-sig/2 boundary and cover every metadata key exceptintegrity; genuine tine-sig/1 signatures remain verifiable. Commands such as tine tag remove the attached signature on re-save rather than leaving a stale authenticity claim. manifest.budget and the top-leveldraft flag are protected; derived metadata.budget_state is not.

Draft checkpoints

Autosave writes atomic checkpoints with a protected top-level draft flag. Consumers can distinguish an incomplete checkpoint from a clean final artifact.

Compatibility

  • opentine 0.8 reads v1 and v2 portable artifacts.
  • Artifacts and repositories written by published releases 0.3.0 through 0.7.2 are covered by the compatibility gate.
  • Loading v1 migrates in memory without rewriting the source.
  • Saving the loaded run writes v2.
  • 0.1.x clients cannot read v2.
  • The legacy 0.1.0 linear importer is best-effort and recomputes step IDs.

Not repository v3

A .tine file remains format v2 in opentine 0.8. A directory named .tine/ is a different surface containing typed v3 objects, refs, reflogs, packs, and indexes. Import a verified portable file with tine migrate-v3; do not rename the file or treat the two formats as byte-compatible.

Use the v0.8 guide for the current compatibility boundary, the v0.4 guide for fork identity, the historical v1-to-v2 guide for old portable files, and the v0.3 guide for repository migration.