graph

Documentation

Overview

Package graph defines the portable graph vocabulary shared across hawk-eco.

The package contains data contracts only. Individual repositories retain ownership of their graph storage, projections, and runtime behavior.

Graph Engineering Patterns: This package implements the foundational patterns from LangGraph, Microsoft AutoGen, and Google ADK for multi-agent orchestration as nodes, edges, and shared state.

Index

• type ArtifactRef
• type Edge
  • func (e Edge) Validate() error
• type EdgeCondition
• type EdgeKind
  • func ParseEdgeKind(s string) (EdgeKind, error)
• type EdgeSpec
  • func (s EdgeSpec) Validate() error
• type Event
  • func (e Event) Validate() error
• type EventType
  • func ParseEventType(s string) (EventType, error)
• type GraphSpec
  • func (s GraphSpec) Validate() error
• type Node
  • func (n Node) Validate() error
• type NodeKind
  • func ParseNodeKind(s string) (NodeKind, error)
• type NodeSpec
  • func (s NodeSpec) Validate() error
• type NodeType
  • func ParseNodeType(s string) (NodeType, error)
• type Provenance
  • func (p Provenance) Validate() error
• type Ref
  • func (r Ref) Validate() error
• type Scope

Types

type ArtifactRef

type ArtifactRef struct {
	URI       string `json:"uri"`
	Digest    string `json:"digest,omitempty"`
	MediaType string `json:"media_type,omitempty"`
}

ArtifactRef points to immutable evidence outside the contract payload.

type Edge

type Edge struct {
	ID          string            `json:"id"`
	Kind        EdgeKind          `json:"kind"`
	From        Ref               `json:"from"`
	To          Ref               `json:"to"`
	Scope       Scope             `json:"scope,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	EffectiveAt time.Time         `json:"effective_at,omitempty"`
	Provenance  Provenance        `json:"provenance"`
	Attributes  map[string]string `json:"attributes,omitempty"`
}

Edge is a typed, temporal relationship between two graph nodes.

func (Edge) Validate

func (e Edge) Validate() error

Validate reports whether e satisfies the minimum shared graph contract.

type EdgeCondition

type EdgeCondition struct {
	Expression string            `json:"expression,omitempty"`
	Variables  map[string]string `json:"variables,omitempty"`
}

EdgeCondition represents a conditional edge in orchestration graphs. When non-empty, the edge is only followed if the condition evaluates to true.

type EdgeKind

type EdgeKind string

EdgeKind identifies a portable relationship between two graph nodes.

const (
	EdgeContains    EdgeKind = "contains"
	EdgeDependsOn   EdgeKind = "depends_on"
	EdgeReferences  EdgeKind = "references"
	EdgeProduced    EdgeKind = "produced"
	EdgeGovernedBy  EdgeKind = "governed_by"
	EdgeValidatedBy EdgeKind = "validated_by"
)

func ParseEdgeKind

func ParseEdgeKind(s string) (EdgeKind, error)

ParseEdgeKind normalizes a graph edge kind.

type EdgeSpec

type EdgeSpec struct {
	From      string         `json:"from"`
	To        string         `json:"to"`
	Condition *EdgeCondition `json:"condition,omitempty"`
	Weight    float64        `json:"weight,omitempty"`
}

EdgeSpec describes an edge in an orchestration graph.

func (EdgeSpec) Validate

func (s EdgeSpec) Validate() error

Validate reports whether s satisfies the minimum edge spec contract.

type Event

type Event struct {
	ID             string     `json:"id"`
	Type           EventType  `json:"type"`
	Subject        Ref        `json:"subject"`
	Scope          Scope      `json:"scope,omitempty"`
	OccurredAt     time.Time  `json:"occurred_at"`
	CorrelationID  string     `json:"correlation_id,omitempty"`
	CausationID    string     `json:"causation_id,omitempty"`
	IdempotencyKey string     `json:"idempotency_key,omitempty"`
	Provenance     Provenance `json:"provenance"`
}

Event records an immutable lifecycle observation for a graph subject.

func (Event) Validate

func (e Event) Validate() error

Validate reports whether e satisfies the minimum shared graph event contract.

type EventType

type EventType string

EventType identifies a lifecycle event for a graph subject.

const (
	EventCreated      EventType = "created"
	EventUpdated      EventType = "updated"
	EventTransitioned EventType = "transitioned"
	EventObserved     EventType = "observed"
	EventDeleted      EventType = "deleted"
)

func ParseEventType

func ParseEventType(s string) (EventType, error)

ParseEventType normalizes a graph event type.

type GraphSpec

type GraphSpec struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Nodes       []NodeSpec        `json:"nodes"`
	Edges       []EdgeSpec        `json:"edges"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

GraphSpec describes a complete orchestration graph.

func (GraphSpec) Validate

func (s GraphSpec) Validate() error

Validate reports whether s satisfies the minimum graph spec contract.

type Node

type Node struct {
	ID          string            `json:"id"`
	Kind        NodeKind          `json:"kind"`
	Scope       Scope             `json:"scope,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	EffectiveAt time.Time         `json:"effective_at,omitempty"`
	Provenance  Provenance        `json:"provenance"`
	Attributes  map[string]string `json:"attributes,omitempty"`
}

Node is a typed, temporal graph fact. Attributes are intentionally bounded to strings; large or sensitive data belongs in ArtifactRef evidence.

func (Node) Validate

func (n Node) Validate() error

Validate reports whether n satisfies the minimum shared graph contract.

type NodeKind

type NodeKind string

NodeKind classifies a node by the ecosystem view to which it belongs.

const (
	NodeSystem     NodeKind = "system"
	NodeKnowledge  NodeKind = "knowledge"
	NodeExecution  NodeKind = "execution"
	NodePolicy     NodeKind = "policy"
	NodeQuality    NodeKind = "quality"
	NodeOperations NodeKind = "operations"
)

func ParseNodeKind

func ParseNodeKind(s string) (NodeKind, error)

ParseNodeKind normalizes a graph node kind.

type NodeSpec

type NodeSpec struct {
	ID          string            `json:"id"`
	Type        NodeType          `json:"type"`
	Name        string            `json:"name,omitempty"`
	Description string            `json:"description,omitempty"`
	Config      map[string]string `json:"config,omitempty"`
}

NodeSpec describes a node in an orchestration graph.

func (NodeSpec) Validate

func (s NodeSpec) Validate() error

Validate reports whether s satisfies the minimum node spec contract.

type NodeType

type NodeType string

NodeType represents the specific type/behavior of a node in the graph

const (
	// NodeTypeAgent represents an autonomous agent that can make decisions
	NodeTypeAgent NodeType = "agent"
	// NodeTypeTool represents a tool/function that agents can invoke
	NodeTypeTool NodeType = "tool"
	// NodeTypeFunction represents a function node (deterministic operation)
	NodeTypeFunction NodeType = "function"
	// NodeTypeStart represents the entry point of a graph
	NodeTypeStart NodeType = "start"
	// NodeTypeEnd represents the termination point of a graph
	NodeTypeEnd NodeType = "end"
	// NodeTypeRouter represents a conditional routing node
	NodeTypeRouter NodeType = "router"
	// NodeTypeQuality represents a code quality analysis node
	NodeTypeQuality NodeType = "quality"
	// NodeTypeExecution represents an execution journal node
	NodeTypeExecution NodeType = "execution"
	// NodeTypeOperations represents an operations orchestration node
	NodeTypeOperations NodeType = "operations"
	// NodeTypeSystem is an alias for NodeKindSystem for backward compatibility
	NodeTypeSystem NodeType = "system"
)

func ParseNodeType

func ParseNodeType(s string) (NodeType, error)

ParseNodeType normalizes a graph node type.

type Provenance

type Provenance struct {
	Producer string        `json:"producer"`
	Version  string        `json:"version,omitempty"`
	SourceID string        `json:"source_id,omitempty"`
	Evidence []ArtifactRef `json:"evidence,omitempty"`
}

Provenance identifies the producer and evidence for a graph fact.

func (Provenance) Validate

func (p Provenance) Validate() error

Validate reports whether p can support an auditable graph fact.

type Ref

type Ref struct {
	Kind NodeKind `json:"kind"`
	ID   string   `json:"id"`
}

Ref identifies a graph node without embedding its mutable attributes.

func (Ref) Validate

func (r Ref) Validate() error

Validate reports whether r can safely identify a graph node.

type Scope

type Scope struct {
	TenantID     string `json:"tenant_id,omitempty"`
	ProjectID    string `json:"project_id,omitempty"`
	RepositoryID string `json:"repository_id,omitempty"`
}

Scope limits a graph fact to its authorized ecosystem boundary. Empty fields are valid for local-only or global facts.