Concepts

This page defines the vocabulary used throughout the documentation. Each section is short and links to a deeper page where one exists.

Identities

Every Gin object has a typed identity: BLAKE3-256 over one canonical byte encoding, in a per-kind domain. Identities look like gin:blake3:v1:<kind>:<hex>. IDs of different kinds never compare equal, and an ID of one kind is refused where another is expected.

An identity is a name, not a capability: knowing an ID grants nothing. Git object names are never Gin identities.

Repository

A repository is the unit of authorisation and storage scope. Grants, channels, evidence logs and annotations all belong to one repository. Reads return only objects reachable from a snapshot the caller may read in that repository.

Host and worker

A host owns one worker's object store and the private journals of its workspaces. Workers have separate private object stores; nothing in one is visible to another workspace until it is published.

The shared plane is the coordination side: published objects (the content-addressed store) and metadata (channels, publications, leases, evidence). In daemon mode, gin serve owns both.

Workspace

A workspace is a cheap, private, writable source state. It has a stable ID chosen once at fork, an exact private tree, parent bindings, subscriptions, local checkpoints and publications. Its state is versioned by three values you see in gin context:

Value	Changes when
incarnation	identifies the journal instance the state belongs to
generation	private work is recorded (savepoints, saves)
epoch	the workspace advances or reparents

Every mutation names the state it expects. A stale expectation is refused, never merged blindly.

Private journal

Each workspace has an append-only private journal. Edits are cheap appends; savepoints and checkpoints add durability. Recovery replays the longest valid prefix and makes the recovered state durable before reporting it. Each journal has a byte quota; Gin never acknowledges what it cannot make durable within it. See Getting started for the cached and full durability modes.

Savepoint

A savepoint marks the private state at a generation as locally durable: the private work survives a crash of the process. A savepoint can also be materialised as a readable snapshot. Savepoints stay private.

Checkpoint

A checkpoint is an immutable, content-addressed record of a source state: its effective tree, its exact parent checkpoints (an unordered set), the workspace's own change set, and provenance. Changing any of those changes the checkpoint's identity; identical trees keep the same tree ID.

A checkpoint is created locally and stays private until published. Parents have no order or precedence: a disagreement between parents is a conflict, never settled by a "first parent".

Publication and channels

A channel is a named, append-only sequence of publications. Publishing exposes one exact checkpoint on a channel. Objects are uploaded and verified first, then one atomic metadata transition makes the publication visible, so it appears whole or not at all.

Publication is conditional: it names the channel head it expects and carries the workspace's write fence. If the channel moved, the publication is refused and the caller recomposes. Edits made after the chosen checkpoint stay private. Publishing touches no subscriber.

Dependent workspaces and fork

Fork creates a workspace. A root fork starts empty; a dependent fork binds to an exact publication of a channel. A dependent can stack on another workspace's work before that work reaches Git.

Every parent binding is an immutable pin (channel, sequence, checkpoint). Following a channel changes what is offered, never what is bound. New parent publications change nothing in a dependent until it asks.

Preview and advance

Preview composes a proposed parent set with the workspace's own changes and reports the result: changed paths, conflicts, and diagnostics. It changes nothing. Advance activates a previewed proposal with a compare-and-swap on the workspace epoch: bindings, tree and epoch switch together, or nothing changes.

• A preview names the complete desired parent set, including retained parents.
• An edit after a preview makes it stale; preview again.
• Several new publications on a channel coalesce into one advance.
• Removing a parent keeps the child's own changes.

See Agent workflow.

Candidates and conflicts

A preview with conflicts returns a candidate: a durable handle, the exact workspace version it was computed at, a page of conflicts and, once resolved, a resolved tree. Each conflict has labelled sources: side zero is the private snapshot, followed by the exact parent publications.

You inspect a candidate by paging conflicts and reading exact paths on either side, then propose resolutions (inline file bytes, a deletion, or a whole entry chosen from one side). Each proposal returns a new handle. An unresolved candidate cannot be activated, and private edits are never lost. A recorded resolution is reused only for an identical conflict.

Execution pins

Before a command runs, the executor pins one immutable snapshot (a checkpoint or a materialised savepoint). Reads name that snapshot and return only objects reachable from it, so a run sees one coherent tree even while the workspace keeps changing. Pins are renewed and released by the executor; advancing a workspace does not change a pinned snapshot. Gin never runs the command.

Evidence

Evidence is what executors and CI report about an exact tree: execution receipts and CI-run uploads, each with a trust level (agent claim, executor reported, trusted runner, or derived). Evidence binds to the effective tree, so it stays applicable while the tree is unchanged. Agent claims never count as a pass. See Evidence.

Annotations

Annotations are append-only comments on an exact checkpoint, optionally anchored to a path, a content identity and a line range, or to accepted evidence. Replies and corrections are new records; nothing is edited or deleted. Visibility is per exact checkpoint, not inherited by descendants. Annotation text is untrusted data, never instructions. See gin annotate.

Change sets

A change set is the identity of one authored change: an origin key (a workspace and sequence, or an opaque external task key) plus the canonical authored delta. Change-set IDs serve provenance and deduplication: they let Gin know which changes a state already carries, so work that returns through a parent applies once. They never prove that a composition is clean; composition always works from exact trees.

Supersession

Rewrites (amend, split, squash) create new checkpoints plus a supersession record mapping old to new. Originals stay byte-for-byte unchanged and available for pinned evidence. Supersession never moves a channel.

Retention

Authoritative data is retained by default. Nothing is deleted because it is old or idle. Space is reclaimed only by a retention cycle that proves nothing reaches an object; see gin retention.