[Paper/M1][P0] Pin Mega namespace bindings across native scopes and import repositories

[Ivanbeethoven]

Parent research epic: #39
Related: #42 (snapshot read adapter), #43 (CAS identity), #44 (refresh), #51 (shared lower), #53 (Libra/Orion).

Problem

The current SnapshotId draft assumes one repository/commit/tree can describe a mounted monorepo subtree. Mega's namespace can cross native scopes, import repositories, and intermediate directories. Fixed blob OIDs alone do not freeze path ownership or import revisions.

This issue tracks the missing namespace contract. It precedes the composite-view portion of #42; single-source fake-backend work in #42 and M0 work can proceed in parallel.

Verified baseline (2026-09-06)

Mega: c4c79bc195541a13ac1505b94728c81a8ff3d603; ScorpioFS: 6a2e7f2ddb7d913b497167f76ff6539bfbb983c2. These are upstream source checks, not a claim about the running deployment.

1. Native refs have (path, ref_name) scope. A child-scope commit tree is not rooted at monorepo /: mega_refs, parent tree/ref updates.
2. REST routing uses the configured import directory and registered repository boundaries: api_handler.
3. Native tree reads already accept commit/tag selectors, but import get_root_tree ignores refs and reads the default ref: native, import.
4. Import attach constructs placeholder path trees rather than embedding the complete import content into the native root: receive-pack handler.
5. /file/tree?path=...&oid=... checks a current path tree against an optional OID; it is not historical tree lookup: tree_ops.

Proposed contract (draft, policy decisions pending)

• SourceSnapshot: instance/source/repo identity, commit OID, tree OID, object format, explicit scope_path.
• NamespaceView: native snapshot + immutable path-to-source bindings index + explicit candidate overrides + materialization policy.
• view_id: immutable descriptor identity; projection_key: content/routing identity for sharing; workspace generation, delta_seq, and server publication_seq have separate semantics.
• Ordinary native directories derive from one selected native root. Independent native scope commits are explicit scoped selections, not silently mixed global revisions.
• Import directories resolve a selected commit/tree once. Intermediate directory listings and repository boundaries are frozen by the view.
• Versioned import paths still pin content OIDs. Names such as 1.3.0 do not prove content immutability.
• CL views record base namespace view, scope, base/head commit and delta digest. A moved CL creates a new candidate identity.
• Scale the bindings index incrementally; no full registry enumeration on each mount.

Work

• Freeze directory classification, path scope and typed selector/error schema with public fixtures.
• Specify Mega source/tree/blob APIs that honor explicit revisions for both native and import sources.
• Define a namespace publication protocol covering native merge, import update/register/remove/rename/default-ref changes.
• Publish native root and bindings through one authoritative view pointer; validate referenced objects before publication.
• Freeze routing and pagination per view; reject conflicting prefixes and unsupported source kinds.
• Define history retention/leases so lazy reads of old views survive remote ref movement and GC.
• Distinguish source-snapshot.v1, replayable view-lock.v1, and atomically published namespace-snapshot.v1.
• Reject historical full-view reconstruction when the historical bindings were not recorded; never fill with current import heads silently.
• Update [Paper/M1][P0] Add revision-addressable tree backends and immutable SnapshotId semantics #42/[Paper/M1][P0] Replace inode-local content storage with a shared content-addressed snapshot cache #43/[Paper/M1][P0] Implement transactional lower-generation switching with crash recovery #44/[Paper/M2][P0] Add a shared FetchCoordinator with single-flight, priority, fairness, and cancellation #50/[Paper/M2][P0][RFC] Decouple shared snapshot lowers from per-workspace writable overlays #51/[Paper/M3][P0] Integrate immutable snapshot lifecycle with Libra/Orion and add a tree correctness oracle #53 acceptance criteria to include source scope and namespace identity.
• Keep production shared-mount architecture selection conditional on refresh and delta-observer correctness.

Mega-side implementation is a cross-repository dependency to scope separately. This issue does not claim those changes have been implemented or approved for deployment.

Acceptance

• Native A/B and import A/B can coexist; old workspaces keep their exact trees after branch movement.
• Root commit and child-scope commit resolve the same intended child contents without duplicated path prefixes.
• Adding or removing an import does not change old view directory listings/routing.
• Concurrent native/import updates expose only a valid published combination; explicit client composition is labeled as such.
• Version-number directory replacement, if allowed by policy, preserves old snapshot readability.
• Different commits with equal visible content retain provenance while sharing eligible caches.
• Historical root with missing routing catalog returns HISTORICAL_BINDINGS_UNAVAILABLE.
• A public independent tree oracle covers native, imported, intermediate and CL views.
• Large-registry/small-working-set test proves mount avoids an O(all repositories) scan.

Decisions requiring owner confirmation

1. Recommend Mega-published composite views; alternative is source-only first, with full-namespace consistency deferred.
2. Recommend immutable published version-number paths; alternative permits replacement with retained historical objects.
3. Recommend existing tasks stay pinned and existing mounts update at controlled pause/restart boundaries; transparent live refresh needs a separate handle/mmap/cwd protocol.

Draft specs have been prepared locally on codex/system-paper-spec: docs/spec/monorepo-versioning.md and docs/spec/system-paper-spec.md. They are not yet published on the default branch. The questions above remain pending; recommendations are not recorded as accepted decisions.

[Ivanbeethoven]

Implementation counterpart: this issue describes the contract for a namespace that crosses native scopes, import repositories and intermediate directories. The concrete implementation slice in the mega2 repository (the refactored monoengine) is tracked as gitmono-dev/mega2#18 — persistent projection (locators/segments) plus import/binding/aggregate/release namespaces, including the source_subpath rule and the byte-identity gate against the current on-the-fly page builder.

Relationship, so the two do not get worked twice:

• this issue (and the research epic [Research Epic] Build snapshot-multiplexed monorepo workspaces for a ScorpioFS systems paper #39) owns the definition — what a composed namespace is, how path ownership and import revisions are frozen;
• mega2#18 owns the server implementation and its acceptance (NS-01..10, ING-01..10) once the definition lands.

The MST/2 read surface in mega2 currently serves native scopes only (capabilities.features.bindings = false), so nothing here is blocked by #18; the reverse is not true — #18 should not start before the contract is settled.