Portable .tine v2

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.

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. Signatures use thetine-sig/1 boundary and cover the body plus an allowlist that now includesmetadata.fork. Tags remain excluded, and commands such as tine tagremove the attached signature on re-save. 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.7 reads v1 and v2 portable artifacts.
Stored data written by published releases 0.3 through 0.6 is 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.7. 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.7 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.