Repository v3

A .tine/ repository is the Git-shaped persistence surface introduced in 0.3.0. It is separate from portable *.tine v2 files.

Object model

blob: raw prompts, outputs, patches, tool results, artifacts, and manifests.
event: normalized model, tool, human, policy, approval, subagent, or error activity.
run: roots and tips plus code, environment, policy, budget, and pricing manifests.
attestation: evaluations, approvals, signatures, and provenance claims.
annotation: separately versioned human or system metadata.

IDs use TYPE:sha256:HEX and bind the object type, schema version, and canonical stored bytes. JSON uses RFC 8785 canonical encoding; blobs retain raw bytes. Credential redaction happens before canonicalization and hashing.

Terminal

tine init .
tine migrate-v3 result.tine --repo . --ref heads/main
tine fsck --repo .
tine repo-log heads/main --repo .
tine object run:sha256:... --repo . --resolve-blobs
tine pack --repo . --output run.pack

Refs and verification

Repositories accept heads/, experiments/, promotions/, annotations/, tags/, and remotes/. Run-moving refs are type-checked, and updates use compare-and-swap so a stale writer cannot silently replace a concurrent update.

fsck recomputes object IDs and validates canonical envelopes, typed links, refs, shallow boundaries, and the event DAG. --shallow skips linked-object checks; it is not equivalent to a complete deep verification.

repository.py

1from opentine import Repo
2
3repo = Repo.init("workspace")
4blob_id = repo.put("blob", b"artifact")
5repo.update_ref("tags/example", blob_id, expected_old=None)
6
7assert repo.get(blob_id).body == b"artifact"
8assert repo.fsck(deep=True).ok

Semantic operations

Repository APIs support log, search, minimal causal context slices, semantic diff, fork, resume, evaluation, attestation, and promotion. Diff reports common and divergent events plus usage, billing, cost, latency, tool path, artifacts, and evaluation scores. It does not line-merge transcripts.

Packs and shallow history

TINEPACK3 packs contain verified envelopes behind a canonical manifest and checksum. Transfers and decompression are bounded at 256 MiB. Shallow log, diff, and context operations stop at the recorded boundary, so aggregates are lower bounds; loading, forking, or resuming a run whose events lie beyond that boundary refuses until history is deepened.

Checked-out and archived repositories

Since version 0.4, a writable repository recreates expected empty directories on a best-effort basis after Git or an archive omits them; read-only copies remain readable. A missing packs/ directory is treated as an empty pack store. This is a layout recovery rule, not permission to ignore missing objects or failed deep verification.

Read the tagged repository protocol for exact invariants and implementation ceilings.