sagaref

package

v0.1.0 Latest Latest Go to latest Published: Sep 4, 2026 License: MIT Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/twentyideas/changesaga

Links

Open Source Insights

Documentation ¶

Overview ¶

Package sagaref defines portable, revision-pinned references to targets in another Change Saga. It deliberately contains no checkout or Saga-storage code; availability is a resolution concern, not part of URI validity.

Index ¶

Constants
func Build(reference Reference) (string, error)
func CanonicalRepository(value string) (string, error)
func CanonicalViewURL(value string) (string, error)
func Validate(reference Reference) error
type QueryRequest
- func NewQueryRequest(reference Reference) (QueryRequest, error)
type QueryResult
type Reference
- func Parse(value string) (Reference, error)
type Resolution
type ResolutionStatus
type Resolver
type Target
- func ParseTarget(value string) (Target, error)
- func (target Target) URN() string
type TargetKind
type VersionedQueryAPI

Constants ¶

View Source

const (
	Scheme  = "saga-ref"
	Version = "v1"
)

View Source

const QueryAPIVersion = "change-saga.ai/v1"

View Source

const SlideQueryAPIVersion = "change-saga.ai/v2"

Variables ¶

This section is empty.

Functions ¶

func Build ¶

func Build(reference Reference) (string, error)

Build validates reference and returns its canonical portable URI. Values with canonical equivalents, such as an upper-case Git OID or a repository URL containing a default port, are normalized before validation.

func CanonicalRepository ¶

func CanonicalRepository(value string) (string, error)

CanonicalRepository returns the portable repository identity. Credentials, query parameters, and fragments are never part of that identity.

func CanonicalViewURL ¶

func CanonicalViewURL(value string) (string, error)

CanonicalViewURL validates and canonicalizes a browser navigation hint. Unlike repository identity, a view URL may retain a query and fragment.

func Validate ¶

func Validate(reference Reference) error

Validate checks the canonical structured representation. It performs no filesystem or network access.

Types ¶

type QueryRequest ¶

type QueryRequest struct {
	Schema         string
	SagaPath       string
	SagaID         string
	Revision       string
	TargetURN      string
	TrackingBranch string
}

QueryRequest is the transport-neutral request made against the referenced Saga's versioned query API. Revision always carries the pinned Git OID; TrackingBranch is refresh metadata only.

func NewQueryRequest ¶

func NewQueryRequest(reference Reference) (QueryRequest, error)

NewQueryRequest converts a validated reference to a versioned query request.

type QueryResult ¶

type QueryResult struct {
	Status          ResolutionStatus
	Target          *Target
	CurrentRevision string
	Detail          string
}

QueryResult is the minimum projection a resolver needs from the other Saga's query API.

type Reference ¶

type Reference struct {
	Repository     string
	SagaPath       string
	SagaID         string
	Revision       string
	TargetURN      string
	TrackingBranch string
	ViewURL        string
}

Reference is the structured form of a saga-ref://v1/target URI. Repository, Revision, and TargetURN are immutable identities. TrackingBranch and ViewURL are optional refresh and navigation hints and never affect which target is resolved.

func Parse ¶

func Parse(value string) (Reference, error)

Parse accepts only the canonical saga-ref://v1 representation.

type Resolution ¶

type Resolution struct {
	Status          ResolutionStatus
	Reference       Reference
	Target          *Target
	CurrentRevision string
	Detail          string
}

Resolution is the transport-neutral result of resolving a portable reference. CurrentRevision is useful for a stale result; it never changes Reference.Revision or silently retargets the reference.

type ResolutionStatus ¶

type ResolutionStatus string

ResolutionStatus is independent of transport success and containing-Saga validity. In particular, unavailable is a valid resolution outcome.

const (
	StatusResolved    ResolutionStatus = "resolved"
	StatusStale       ResolutionStatus = "stale"
	StatusUnavailable ResolutionStatus = "unavailable"
)

type Resolver ¶

type Resolver interface {
	Resolve(context.Context, Reference) (Resolution, error)
}

Resolver resolves a portable reference. Implementations may report StatusUnavailable when no checkout or external service is available; that outcome must not be interpreted as structural invalidity of the reference.

type Target ¶

type Target struct {
	SagaID   string
	Kind     TargetKind
	ID       string
	ParentID string
}

Target is the parsed identity embedded in Reference.TargetURN. ParentID is the story ID for a criterion and the fragment ID for a landmark.

func ParseTarget ¶

func ParseTarget(value string) (Target, error)

ParseTarget validates a canonical stable target URN.

func (Target) URN ¶

func (target Target) URN() string

URN returns target's canonical stable URN, or an empty string when target is not a supported shape.

type TargetKind ¶

type TargetKind string

TargetKind identifies a stable target shape supported by cross-Saga references.

const (
	TargetStory        TargetKind = "story"
	TargetCriterion    TargetKind = "criterion"
	TargetPrototype    TargetKind = "prototype"
	TargetChapter      TargetKind = "chapter"
	TargetSection      TargetKind = "section"
	TargetFragment     TargetKind = "fragment"
	TargetLandmark     TargetKind = "landmark"
	TargetDeck         TargetKind = "deck"
	TargetSlide        TargetKind = "slide"
	TargetItem         TargetKind = "item"
	TargetWorkItem     TargetKind = "work-item"
	TargetClaim        TargetKind = "claim"
	TargetVerification TargetKind = "verification"
)

type VersionedQueryAPI ¶

type VersionedQueryAPI interface {
	ResolveTarget(context.Context, QueryRequest) (QueryResult, error)
}

VersionedQueryAPI is the only Saga-content boundary used by checkout-aware resolvers. An implementation may execute a local CLI or call another transport, but must query Schema and must not read .saga metadata directly. A checkout locator belongs outside this package and supplies an implementation only when the pinned repository revision is available.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL