Architecture

This page is a deep dive. You do not need it for day-to-day use. Start with Versioned File Systems or Git Repositories first. File systems and repositories share the mount client and product concepts but store history in two different engines.

​

Overview

Tensorlake separates metadata from file content.

• The control plane stores history metadata — for repositories that’s Git commits, refs, branches, and private workspace WAL checkpoints; for file systems it’s native content-addressed snapshots and per-session checkpoint journals — plus sessions, workspaces, and operation history.
• The data plane stores file content in blob storage (Git objects for repositories, content-addressed blobs for file systems).
• Mounts resolve metadata through the control plane and fetch file content lazily from the data plane.

This split keeps session creation, snapshot listing, and history fast even when a file system or repository is large.

​

Two storage engines, one mount client

File systems and repositories share the mount/overlay client, crash-safe local journal, and lazy content delivery, but they store and publish history through different engines:

• Repositories are Git. History is Git commits, refs, and branches; content is packed into Git objects; they speak Git smart-HTTP so git clone/push work.
• File systems run the native snapshot engine. History is immutable content-addressed checkpoints and snapshots (not Git commits); file content is deduplicated and packed into content-addressed blobs; and a per-session checkpoint journal is the crash-safe replication path into the shared timeline. File systems have no Git access — no commits, refs, branches, packs, or Git wire protocol.

A session or workspace is metadata, not a full copy. It records what it belongs to, the point it started from, and its durable WAL or snapshot chain. A Git read-only mount creates no workspace; a writable Git workspace is created lazily when its first remote WAL checkpoint arrives. Saving uploads only changed content. Optimization, deduplication, retention, and garbage collection run in the background so agents never wait on storage maintenance.

​

One local journal, two product surfaces

Writable file-system and repository mounts share one crash-safe client pipeline: The difference is publication policy. On tl fs, the server verifies, orders, and applies each autosave checkpoint to the shared drive before acknowledging it; tl fs snapshot adds a permanent retention point. On tl git, autosave checkpoints remain private workspace WAL: they create neither a Git commit nor a branch update. tl git snapshot materializes the current WAL as a workspace commit, and tl git promote deliberately lands it on a branch.

​

Content Delivery

Mounting a repository or file system does not copy it into the sandbox. The mount resolves the tree, then fetches file content lazily as processes read paths. That means:

• Large repositories can mount quickly.
• A sandbox only downloads paths it actually reads.
• Many sandboxes can mount the same repository without a single shared serving path becoming the bottleneck.

Following read-only mounts add branch tracking. When the followed branch moves, Tensorlake compares the old and new commits and invalidates only changed paths. Unchanged files keep their warm page cache.

​

Reconciling concurrent writes

The two engines reconcile concurrent writes differently, because they model history differently. File systems have one linear timeline. When checkpoints race, the server orders them and rebases each update’s changed paths onto the current head before acknowledging it. Cost is proportional to changed paths, not file-system size. Disjoint paths merge automatically; two writers on the same path are last-writer-wins — the later ordered update’s version of that file sticks, silently. There is no three-way merge and no conflict marker on a file system, because a single timeline has nothing to diverge from. See Concurrent Writes. Repositories can have divergent branches, so they use a server-side three-way merge engine, verified against Git’s merge behavior, for promote, git merge, and rebase. It compares the common ancestor, the target branch, and the workspace, resolving non-overlapping edits automatically and surfacing genuine conflicts. tl git sync has a narrower role: it refreshes or switches a read-only or snapshot-free view, carrying its WAL tail forward, and refuses to rewrite an established workspace snapshot chain. Two conflict behaviors apply on the repository surface: Fail (the default for promotion — nothing lands, a structured conflict report is returned) and Materialize (writes Git conflict markers plus a queryable conflict record). Both preserve the losing content in Git history.

​

Promotion

Promotion is the repository surface’s path through the merge engine. It first materializes any dirty workspace WAL, then lands the workspace as one squashed commit. See Repository Mounts for the workflow. File systems have no promote step: replicated autosaves advance the shared timeline automatically, while snapshots make selected points permanent.

​

Observability

Durable file-system and repository state is queryable through the API and available to the control plane:

• Which workspaces are live.
• Which are detached and resumable.
• Which durable WAL checkpoints and snapshots exist.
• Which principal created each snapshot.
• Which paths changed.

For file systems, the durable record is the single timeline’s checkpoint and snapshot history. For repositories, branch activity is also recorded: pushes, promotions, rebases, merges, and materialized conflict records. Mount heartbeats expose liveness, but the unsealed tail of edits remains in the sandbox’s local journal until autosave. The control plane does not observe every in-progress file edit. Detached Git workspaces are collected by lifecycle tier. An actively mounted workspace is retained; a WAL-only detached workspace defaults to 48 hours, and a detached workspace with snapshots defaults to 14 days. The deployment configuration controls these periods.