Glossary: Task Sync

Mirrored from docs/design/task-sync/references/glossary.md. Edit the source document in the repository, not this generated page.

Vocabulary specific to the task-sync feature. Standard git terms (orphan branch in the abstract, refspec, fast-forward) are excluded except where task sync gives them a specific meaning. Standard distributed-systems terms (CRDT, OT, eventual consistency) are excluded — the 3_vision.md §2 section names them in their generic form when needed.

Term	Meaning
Materialized state	The local canonical home bundles under ~/.orbit/tasks/workspaces/<workspace-id>/ plus the .orbit/tasks/<task-id> projection links rebuilt from them. The registry on the orphan branch is the shared store; the workspace projection is a materialized view. See 2_design.md §2.3.
Operation kind	One of a fixed set of structured task mutations (task.add, task.transition, task.comment.append, task.history.append, task.review.append, task.field.update, task.artifacts.upsert, task.delete) recorded in commit messages on the registry. Replay rules in 2_design.md §3.2 are keyed by operation kind.
Operation replay	The behavior on push reject: instead of text-merging, the sync coordinator re-fetches the registry, applies the original operation’s replay rule against the new tip, and pushes again. Some operations always converge (comment.append, history.append); some surface a structured conflict when their baseline has changed (field.update, transition). See 2_design.md §3.2.
Orphan branch	In task sync specifically: the git branch at refs/heads/orbit/tasks that holds the canonical task registry. It has no shared history with code branches, is created with git checkout --orphan, and is never merged into product branches. The pattern itself is a generic git feature; in this feature it’s the registry’s storage. See 2_design.md §2.1.
Registry pull	The operation orbit task sync pull. Fetches the orphan branch ref, updates canonical home bundles, and rebuilds the workspace’s .orbit/tasks/<task-id> projections. Local-only changes are surfaced rather than overwritten. See 2_design.md §6.2.
Registry seed	The first-time enablement operation orbit task sync push --init. Verifies the registry ref does not exist (or is empty) on the remote and seeds it from the workspace’s canonical home bundles plus workspace binding metadata. Subsequent enablements on the same workspace use regular pull/push, not --init. See 2_design.md §6.2.
Same-task conflict	The class of conflict where two operators concurrently mutate the same task (status transition divergence, concurrent same-field edits). Distinguished from counter collision (concurrent ADD with the same allocated ID), which is auto-resolvable. Same-task conflicts may resolve automatically (append-only operations) or surface to the user as a structured conflict (task.field.update, divergent task.transition). See 2_design.md §3.1.
Soft-claim	An advisory assigned_to field on a task indicating an operator has expressed intent to work on it. A soft-claim is not a lock — it does not prevent another operator from editing the task. The convention is “look before you leap”; the mechanism is a hint. Open questions about expiry, stealing, and per-status claims live in 3_vision.md §1.3.
Structured conflict	A conflict the replay logic could not resolve automatically. Written to .orbit/tasks/_conflicts/<task-id>.yaml with both sides recorded; resolved by the user via orbit task sync resolve <task-id>. Distinct from a git text-merge conflict — structured conflicts are field-level, not line-level. See 2_design.md §3.2.
Sync coordinator	The future code component (orbit-store::sync::TaskSyncCoordinator) that owns git transport, operation classification, and replay logic. Sits above the v2 task store and below runtime/CLI/web entry points. See 2_design.md §5.1.
Task registry	The shared store of task bundles for a team, materialized as a git tree on the orphan branch refs/heads/orbit/tasks. Canonical home bundles and workspace projections are hydrated from the registry when sync is enabled. See 2_design.md §2.1.
Tombstone	A _tombstones/<workspace-id>/<task-id>.yaml entry on the registry recording that a task was deleted, by whom, and when. The active task directory is removed; the tombstone prevents an offline operator’s older task version from resurrecting the task on push. See 2_design.md §3.4 and 4_decisions.md ADR-008.