Skip to content

feat(protocol): expose research lineage — Versions, Branches, Forks and Proposals — through Hub discovery #1748

Closed

Description

@DecisionNerd

Problem

GraphForge has durable research lineage: immutable Versions, Branches with current heads, Forks with origin citations, Proposals, and Branch creation from frozen Slices (ADRs 0039–0044, #1352, #1356, #1357). #1357 defines consumer-neutral references and leaves "URLs and hosting" to associated projects. Hub discovery (#906, extended by #1732) still exposes only complete Project versions, so a Hub can't show or clone any of this lineage.

Objective

Extend the Rust-owned discovery contract with read-only research lineage, so a conforming Hub can render Versions, Branches, Forks and Proposals and link them, and gf clone can fetch an exact Branch head or Version.

Requirements

  • Advertise published research Versions and Branch heads for a repository. Discovery refs map to Branch heads; immutable Version references never follow a later head (ADR 0044).
  • Expose Fork origin citations (original Project identity and source Version) and Branch genealogy (parent, base Version, ultimate Project lineage) as typed references with exact identities.
  • Expose Slice provenance only as a Branch creation selection commitment. No persistent Slice entity (ADR 0040).
  • Expose published Proposal packages as frozen, selected projections with their source Branch/Version identity; review decisions remain destination-local.
  • Clone or import an exact Branch head or Version through the existing research interchange component, with the same verification, atomicity and network-safety rules as gf clone.
  • Keep package, transport, Project, Version and projection identities distinct. A redacted or partial projection never masquerades as the complete Version.
  • Unknown required research capabilities fail closed with unsupported_future before object reads or project mutation.
  • Update the JSON Schema and conformance corpus with a fixture that has a Fork, two Branches and a Proposal.

Acceptance

  • A consumer can list a repository's Branches and Versions, resolve "forked from" to the origin Project identity, and clone a Branch head and an immutable Version into distinct destinations that reopen with identical lineage.
  • A partial projection is reported as a projection of its source Version, not as that Version.

Non-goals

Related

#906, #1732, #1352, #1356, #1357, ADRs 0039–0044; CurateLabs/graphforge-nextjs M3.

Metadata

Metadata

Assignees

No one assigned

    Labels

    coreCore source code changesenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions