[Initiative] GitLab-style repository storage identity and path strategy

[juliuskrah]

Summary

Define and implement a repository storage strategy that decouples user-facing namespace from physical storage layout, aligned with GitLab-style repository storage paths. The platform should resolve namespace/repo externally while persisting repositories using an internal stable identity (repo_id/UUID) and fanout storage paths for operational scalability.

Scope

In scope:

• Define repository identity model with two layers:
  • external identity: namespace/repo
  • internal identity: stable repo_id (opaque identifier)
• Adopt GitLab-style storage path strategy where internal storage is not the namespace canonical source of truth.
• Define deterministic filesystem path resolution from internal ID using fanout (hashed/path segmented layout).
• Specify rename and transfer semantics so namespace changes do not require physical repository moves.
• Define how this model fits current architecture (api + git-service) and transport protocols (HTTP, SSH, gRPC roadmap).
• Define storage metadata contracts required for routing and repository lookup.
• Document rollout and compatibility expectations.

Out of scope:

• Full object-store-native repository backend replacement in this initiative.
• Large-scale shard rebalancing across multiple storage clusters.

Acceptance Criteria

• A canonical storage decision record exists: namespace-visible path vs internal-ID-backed path (selected: internal-ID-backed with fanout).
• Repository resolution contract is defined: namespace/repo -> repo_id -> storage_path.
• Rename/transfer operations are specified to avoid mandatory repository data moves.
• git-service can resolve repositories via internal identity mapping rather than relying on namespace-as-path assumptions.
• Operational docs describe storage layout, lookup flow, and debugging steps.

Tracking

• Depends on [Initiative] Namespaces #39
• Subtasks will track schema, resolver implementation, migration, protocol integration, and docs/runbooks.
• Milestone: TBD