Forking architecture

# Forking architecture

How a fork is created, stored, and represented, and the decisions behind it.

## Component map

- **`GitRepositoryService.fork(User actor, Repository source)`** — the single
  entry point. Validates read access, checks for a name collision in the
  actor's namespace, persists the new `Repository` row (with `parent` set to the
  source), then clones the bare repository on disk. Reused by every surface.
- **`Repository.parent`** (`@ManyToOne`, column `parent_repo_id`) — the fork
  link. `@ManyToOne` is EAGER by default, so `parent` loads with the repository
  and both the API projection and the Qute sidebar can render “forked from …”
  without a second query. `Repository.isFork()` is the null check.
- **`RepositoryApiResource.fork`** — `POST /api/v1/repos/{owner}/{name}/fork`,
  returns `201`/`409`/`404`/`401`.
- **`RepositoryTools.forkRepository`** — the MCP mirror of the REST endpoint.
- **`RepositoryResource.fork`** — the UI `POST …/fork`, redirecting to the fork.
- **`ApiModels.RepositoryView`** — carries `parentOwner`/`parentName`.

## Data flow

1. The surface resolves the source through the normal visibility gate
   (`requireReadable`), so an unreadable private source is a `404`/`403` before
   `fork()` runs.
2. `fork()` re-checks `accessPolicy.canRead(actor, source)` — defense in depth,
   independent of the caller — then guards against a duplicate name in the
   actor's namespace.
3. It persists the fork row inside the method's transaction.
4. It clones the source's bare repository into the fork's on-disk path with
   `Git.cloneRepository().setBare(true).setCloneAllBranches(true)` over a
   `file://` URI, copying HEAD, all branches, and reachable tags.

## Decisions

- **Clone, not filesystem copy.** A JGit bare clone reproduces the ref set and
  object database cleanly and skips source-specific junk (stale `config`
  remotes, hooks). The trade-off is that each fork is an independent object
  store — no shared/alternates dedup — which is acceptable at git-shark's target
  scale and keeps deletion trivial. If storage pressure ever matters, git
  alternates are the place to look.
- **`ON DELETE SET NULL`, not cascade.** Deleting a source must not delete other
  people's forks. A fork whose parent is gone simply loses its “forked from”
  link and becomes a standalone repository.
- **Visibility inherited, never widened.** The fork takes the source's
  visibility and the actor must already be able to read the source, so forking
  can never turn a private repository public or expose it to someone new.
- **Parent link gated per viewer, not just at fork time.** The "forked from"
  link and the API's `parentOwner`/`parentName` are shown only when the *current
  viewer* can read the parent (`accessPolicy.canRead(viewer, parent)`), computed
  in `RepoNavService` for the UI and via `canSeeParent(...)` in the REST/MCP
  resources. This matters because a source can be flipped to private *after*
  being forked; without the per-viewer check, a public fork would keep leaking
  the now-private parent's owner/name. `RepositoryView.of(repo)` hides the parent
  by default, so listings never disclose it — callers opt in with
  `of(repo, showParent)`.
- **Personal namespace only (v1).** Forks land under the acting user, never an
  organisation. Forking into an org is a future extension.
- **Fork button open to any logged-in reader**, and a repeat fork redirects to
  the caller's existing repository of that name rather than erroring — a
  minimal stand-in for a fork picker.

## What works today

- Fork any readable repository into your personal namespace (UI, REST, MCP).
- Full ref copy: HEAD, all branches, reachable tags.
- `parent`/`isFork` model, “forked from” link, and `parentOwner`/`parentName`
  in the API projection.
- Visibility enforcement (private sources never exposed; private fork of a
  private source), including the per-viewer "forked from" gate that keeps a
  source turned private after forking from leaking through its public forks.
- `ON DELETE SET NULL` so forks outlive their source.

## What still needs to be implemented

- **Cross-repo merge requests** — opening an MR from a fork branch against the
  parent repository. The `parent` link is in place; the MR subsystem does not
  yet target a different repository.
- **Fork syncing** — “update from upstream” to pull later parent changes into a
  fork.
- **Fork discovery** — a fork network/graph view and a “forks” count on the
  source.
- **Forking into an organisation** namespace.
- **Storage sharing** (git alternates) to avoid a full object copy per fork.