graphcontract

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package graphcontract defines Spool's canonical graph object contract.

Index

Constants

View Source 
const (
	// BuiltinSchemaVersion is the version of the initial permissive schema.
	BuiltinSchemaVersion uint16 = 1
	// GlobalInvariantAcyclic requires the directed graph to contain no cycles.
	GlobalInvariantAcyclic GlobalInvariant = "acyclic"
	// GlobalInvariantNoSelfLoop disallows edges whose endpoints are identical.
	GlobalInvariantNoSelfLoop GlobalInvariant = "no-self-loop"
	// UniversalModifierLabel identifies the intrinsic cross-cutting modifier label.
	UniversalModifierLabel = "Ephemeral"
)

Variables

View Source 
var (
	// ErrInvalidPropertyValue reports a property value with an unknown kind or a
	// non-finite floating-point value.
	ErrInvalidPropertyValue = errors.New("invalid property value")
	// ErrInvalidCanonicalCBOR reports CBOR that does not encode a normalized
	// graph contract value in its canonical representation.
	ErrInvalidCanonicalCBOR = errors.New("invalid canonical CBOR")
	// ErrInvalidCommit reports a commit record without its required snapshot or
	// with an empty parent identifier.
	ErrInvalidCommit = errors.New("invalid commit")
)
View Source 
var (
	// ErrInvalidSchemaTOML reports malformed TOML or TOML that does not match
	// the schema authoring format.
	ErrInvalidSchemaTOML = errors.New("invalid schema TOML")
	// ErrInvalidSchemaSnapshot reports a schema snapshot without a version.
	ErrInvalidSchemaSnapshot = errors.New("invalid schema snapshot")
	// ErrInvalidSchemaDefinition reports inconsistent or unsupported schema rules.
	ErrInvalidSchemaDefinition = errors.New("invalid schema definition")
	// ErrInvalidSchemaIdentifier reports an invalid schema identifier.
	ErrInvalidSchemaIdentifier = errors.New("invalid schema identifier")
	// ErrSchemaValidation reports graph contents that do not satisfy a schema.
	ErrSchemaValidation = errors.New("schema validation failed")
)

Functions

func MarshalCommit added in v1.4.0 

func MarshalCommit(c Commit) ([]byte, error)

MarshalCommit returns the normalized, canonical CBOR encoding of c.

func MarshalEdge 

func MarshalEdge(e Edge) ([]byte, error)

MarshalEdge returns the normalized, canonical CBOR encoding of e.

func MarshalNode 

func MarshalNode(n Node) ([]byte, error)

MarshalNode returns the normalized, canonical CBOR encoding of n.

func MarshalPropertyValue 

func MarshalPropertyValue(v PropertyValue) ([]byte, error)

MarshalPropertyValue returns the normalized, canonical CBOR encoding of v.

func MarshalSchemaSnapshot added in v1.4.0 

func MarshalSchemaSnapshot(s SchemaSnapshot) ([]byte, error)

MarshalSchemaSnapshot returns the normalized, canonical CBOR encoding of s.

func ValidateSchemaSnapshot added in v1.4.0 

func ValidateSchemaSnapshot(schema SchemaSnapshot, nodes map[string]Node, edges map[string]Edge) error

ValidateSchemaSnapshot checks fully materialized graph entities against schema. It never mutates nodes or edges.

Types

type Cardinality added in v1.4.0 

type Cardinality struct {
	SourceMin uint32 `json:"sourceMin,omitempty" cbor:"1,keyasint,omitempty"`
	SourceMax uint32 `json:"sourceMax,omitempty" cbor:"2,keyasint,omitempty"`
	TargetMin uint32 `json:"targetMin,omitempty" cbor:"3,keyasint,omitempty"`
	TargetMax uint32 `json:"targetMax,omitempty" cbor:"4,keyasint,omitempty"`
}

Cardinality bounds incoming and outgoing edges of an edge type. A maximum of zero is unbounded.

type Commit added in v1.4.0 

type Commit struct {
	Snapshot ObjectID   `json:"snapshot" cbor:"1,keyasint"`
	Parents  []ObjectID `json:"parents" cbor:"2,keyasint"`
	Message  string     `json:"message" cbor:"3,keyasint"`
	Author   string     `json:"author" cbor:"4,keyasint"`
	Time     time.Time  `json:"time" cbor:"5,keyasint"`
}

Commit is an immutable record that assigns a graph snapshot to a point in the ordered commit DAG. Parents are identity-bearing: their order and repetition are preserved exactly.

func NewCommit added in v1.4.0 

func NewCommit(snapshot ObjectID, parents []ObjectID, author, message string, timestamp time.Time) (Commit, error)

NewCommit constructs a normalized commit record.

func UnmarshalCommit added in v1.4.0 

func UnmarshalCommit(data []byte) (Commit, error)

UnmarshalCommit decodes and verifies canonical CBOR for a commit record.

func (Commit) Clone added in v1.4.0 

func (c Commit) Clone() Commit

Clone returns a deep copy of c.

func (Commit) Equal added in v1.4.0 

func (c Commit) Equal(other Commit) bool

Equal reports semantic equality after canonical normalization.

func (Commit) MarshalCBOR added in v1.4.0 

func (c Commit) MarshalCBOR() ([]byte, error)

MarshalCBOR returns the normalized, canonical CBOR encoding of c. Omitted and explicitly empty parent collections have one encoding.

func (Commit) Normalize added in v1.4.0 

func (c Commit) Normalize() (Commit, error)

Normalize returns the canonical commit representation. It normalizes time to UTC whole seconds, the precision represented by canonical CBOR, and defensively copies parents without changing their order.

func (*Commit) UnmarshalCBOR added in v1.4.0 

func (c *Commit) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes and verifies canonical CBOR for c.

type Edge 

type Edge struct {
	// ID uniquely identifies the edge within a graph snapshot.
	ID string `json:"id" cbor:"1,keyasint"`
	// Source identifies the edge's originating node.
	Source string `json:"source" cbor:"2,keyasint"`
	// Target identifies the edge's destination node.
	Target string `json:"target" cbor:"3,keyasint"`
	// Type identifies the edge's relationship type.
	Type string `json:"type,omitempty" cbor:"4,keyasint,omitempty"`
	// Properties holds typed, recursively composable edge properties.
	Properties map[string]PropertyValue `json:"properties" cbor:"5,keyasint"`
}

Edge is the immutable edge representation stored in a graph snapshot.

func NewEdge 

func NewEdge(id, source, target, edgeType string, properties map[string]PropertyValue) (Edge, error)

NewEdge constructs a normalized edge.

func UnmarshalEdge 

func UnmarshalEdge(data []byte) (Edge, error)

UnmarshalEdge decodes and verifies canonical CBOR for an edge.

func (Edge) Clone 

func (e Edge) Clone() Edge

Clone returns a deep copy of e.

func (Edge) Equal 

func (e Edge) Equal(other Edge) bool

Equal reports semantic equality after canonical normalization.

func (Edge) MarshalCBOR 

func (e Edge) MarshalCBOR() ([]byte, error)

MarshalCBOR returns the normalized, canonical CBOR encoding of e. Omitted and explicitly empty properties have one encoding.

func (Edge) Normalize 

func (e Edge) Normalize() (Edge, error)

Normalize returns a canonical edge with normalized property values.

type EdgeTypeRule added in v1.4.0 

type EdgeTypeRule struct {
	Type         string         `json:"type" cbor:"1,keyasint"`
	Properties   []PropertyRule `json:"properties,omitempty" cbor:"2,keyasint,omitempty"`
	SourceLabels []string       `json:"sourceLabels,omitempty" cbor:"3,keyasint,omitempty"`
	TargetLabels []string       `json:"targetLabels,omitempty" cbor:"4,keyasint,omitempty"`
	Cardinality  Cardinality    `json:"cardinality" cbor:"5,keyasint"`
}

EdgeTypeRule defines constraints for edges of Type.

type GlobalInvariant added in v1.4.0 

type GlobalInvariant string

GlobalInvariant names a graph-wide invariant enforced by a schema validator.

type Node 

type Node struct {
	// ID uniquely identifies the node within a graph snapshot.
	ID string `json:"id" cbor:"1,keyasint"`
	// Title is the node's display value and compatibility field.
	Title string `json:"title" cbor:"2,keyasint"`
	// Labels identifies the node's sorted, unique type labels.
	Labels []string `json:"labels" cbor:"3,keyasint"`
	// Properties holds typed, recursively composable node properties.
	Properties map[string]PropertyValue `json:"properties" cbor:"4,keyasint"`
}

Node is the immutable node representation stored in a graph snapshot.

func NewNode 

func NewNode(id, title string, labels []string, properties map[string]PropertyValue) (Node, error)

NewNode constructs a normalized node.

func UnmarshalNode 

func UnmarshalNode(data []byte) (Node, error)

UnmarshalNode decodes and verifies canonical CBOR for a node.

func (Node) Clone 

func (n Node) Clone() Node

Clone returns a deep copy of n.

func (Node) Equal 

func (n Node) Equal(other Node) bool

Equal reports semantic equality after canonical normalization.

func (Node) MarshalCBOR 

func (n Node) MarshalCBOR() ([]byte, error)

MarshalCBOR returns the normalized, canonical CBOR encoding of n. Omitted and explicitly empty collections have one encoding.

func (Node) Normalize 

func (n Node) Normalize() (Node, error)

Normalize returns a canonical node with sorted, deduplicated labels and normalized property values.

type NodeLabelRule added in v1.4.0 

type NodeLabelRule struct {
	Label            string         `json:"label" cbor:"1,keyasint"`
	Properties       []PropertyRule `json:"properties,omitempty" cbor:"2,keyasint,omitempty"`
	NaturalKey       []string       `json:"naturalKey,omitempty" cbor:"3,keyasint,omitempty"`
	NaturalKeyUnique bool           `json:"naturalKeyUnique,omitempty" cbor:"4,keyasint,omitempty"`
}

NodeLabelRule defines constraints for nodes carrying Label.

type ObjectID added in v1.4.0 

type ObjectID string

ObjectID is a content-derived identifier for an immutable graph object.

type PropertyKind 

type PropertyKind string

PropertyKind identifies the concrete value carried by a PropertyValue. 

const (
	PropertyNull    PropertyKind = "null"
	PropertyBool    PropertyKind = "bool"
	PropertyInteger PropertyKind = "integer"
	PropertyFloat   PropertyKind = "float"
	PropertyString  PropertyKind = "string"
	PropertyList    PropertyKind = "list"
	PropertyMap     PropertyKind = "map"
)

type PropertyRule added in v1.4.0 

type PropertyRule struct {
	Key      string         `json:"key" cbor:"1,keyasint"`
	Required bool           `json:"required" cbor:"2,keyasint"`
	Types    []PropertyKind `json:"types" cbor:"3,keyasint"`
	Indexed  bool           `json:"indexed,omitempty" cbor:"4,keyasint,omitempty"`
}

PropertyRule defines whether a property is required, indexed, and its allowed value kinds.

type PropertyValue 

type PropertyValue struct {
	Kind    PropertyKind             `json:"kind" cbor:"1,keyasint"`
	Bool    bool                     `json:"bool,omitempty" cbor:"2,keyasint,omitempty"`
	Integer int64                    `json:"integer,omitempty" cbor:"3,keyasint,omitempty"`
	Float   float64                  `json:"float,omitempty" cbor:"4,keyasint,omitempty"`
	String  string                   `json:"string,omitempty" cbor:"5,keyasint,omitempty"`
	List    []PropertyValue          `json:"list,omitempty" cbor:"6,keyasint,omitempty"`
	Map     map[string]PropertyValue `json:"map,omitempty" cbor:"7,keyasint,omitempty"`
}

PropertyValue is a tagged, recursively composable graph property value. Only the field associated with Kind is significant.

func BoolPropertyValue 

func BoolPropertyValue(value bool) PropertyValue

BoolPropertyValue returns a boolean property value.

func FloatPropertyValue 

func FloatPropertyValue(value float64) PropertyValue

FloatPropertyValue returns a floating-point property value.

func IntegerPropertyValue 

func IntegerPropertyValue(value int64) PropertyValue

IntegerPropertyValue returns an integer property value.

func ListPropertyValue 

func ListPropertyValue(value []PropertyValue) PropertyValue

ListPropertyValue returns a list property value.

func MapPropertyValue 

func MapPropertyValue(value map[string]PropertyValue) PropertyValue

MapPropertyValue returns a string-keyed map property value.

func NullPropertyValue 

func NullPropertyValue() PropertyValue

NullPropertyValue returns the canonical null property value.

func StringPropertyValue 

func StringPropertyValue(value string) PropertyValue

StringPropertyValue returns a string property value.

func UnmarshalPropertyValue 

func UnmarshalPropertyValue(data []byte) (PropertyValue, error)

UnmarshalPropertyValue decodes and verifies canonical CBOR for a property value.

func (PropertyValue) Clone 

func (v PropertyValue) Clone() PropertyValue

Clone returns a deep copy of v.

func (PropertyValue) Equal 

func (v PropertyValue) Equal(other PropertyValue) bool

Equal reports semantic equality after canonical normalization.

func (PropertyValue) MarshalCBOR 

func (v PropertyValue) MarshalCBOR() ([]byte, error)

MarshalCBOR returns the normalized, canonical CBOR encoding of v.

func (PropertyValue) Normalize 

func (v PropertyValue) Normalize() (PropertyValue, error)

Normalize returns the canonical representation of v. It clears fields that do not belong to v.Kind, recursively normalizes values, and normalizes negative zero to zero. CBOR canonical encoding deterministically orders the resulting string-keyed maps.

type PropertyValueKind 

type PropertyValueKind = PropertyKind

PropertyValueKind is an alias retained for callers that prefer the explicit type name.

type SchemaSnapshot added in v1.4.0 

type SchemaSnapshot struct {
	Version          uint16            `json:"version" cbor:"0,keyasint"`
	Permissive       bool              `json:"permissive" cbor:"1,keyasint"`
	NodeRules        []NodeLabelRule   `json:"nodeRules,omitempty" cbor:"2,keyasint,omitempty"`
	EdgeRules        []EdgeTypeRule    `json:"edgeRules,omitempty" cbor:"3,keyasint,omitempty"`
	GlobalInvariants []GlobalInvariant `json:"globalInvariants,omitempty" cbor:"4,keyasint,omitempty"`
}

SchemaSnapshot is the canonical schema object referenced by a graph snapshot. Version one is retained as the permissive built-in schema; later versions may declare node, edge, and graph-wide validation rules.

func BuiltinSchemaSnapshot added in v1.4.0 

func BuiltinSchemaSnapshot() SchemaSnapshot

BuiltinSchemaSnapshot returns the built-in versioned permissive schema.

func DecodeSchemaTOML added in v1.4.0 

func DecodeSchemaTOML(data []byte) (SchemaSnapshot, error)

DecodeSchemaTOML decodes a schema definition from TOML and returns its normalized canonical representation. Unknown keys are rejected.

func DecodeSchemaTOMLReader added in v1.4.0 

func DecodeSchemaTOMLReader(reader io.Reader) (SchemaSnapshot, error)

DecodeSchemaTOMLReader decodes a schema definition from a TOML stream.

func ParseSchemaTOML added in v1.4.0 

func ParseSchemaTOML(data []byte) (SchemaSnapshot, error)

ParseSchemaTOML is an alias for DecodeSchemaTOML.

func UnmarshalSchemaSnapshot added in v1.4.0 

func UnmarshalSchemaSnapshot(data []byte) (SchemaSnapshot, error)

UnmarshalSchemaSnapshot decodes and verifies canonical CBOR for a schema snapshot.

func (SchemaSnapshot) MarshalCBOR added in v1.4.0 

func (s SchemaSnapshot) MarshalCBOR() ([]byte, error)

MarshalCBOR returns the normalized, canonical CBOR encoding of s.

func (SchemaSnapshot) Normalize added in v1.4.0 

func (s SchemaSnapshot) Normalize() (SchemaSnapshot, error)

Normalize validates and canonicalizes a schema snapshot.

type SchemaValidationError added in v1.4.0 

type SchemaValidationError struct {
	Violations []SchemaViolation
}

SchemaValidationError contains every violation found while validating a materialized graph. Violations are sorted lexically for stable previews.

func (*SchemaValidationError) Error added in v1.4.0 

func (e *SchemaValidationError) Error() string

func (*SchemaValidationError) Unwrap added in v1.4.0 

func (e *SchemaValidationError) Unwrap() error

type SchemaViolation added in v1.4.0 

type SchemaViolation struct {
	Code     SchemaViolationCode `json:"code"`
	Entity   string              `json:"entity"`
	EntityID string              `json:"entityID"`
	Rule     string              `json:"rule,omitempty"`
	Field    string              `json:"field,omitempty"`
	Expected string              `json:"expected,omitempty"`
	Actual   string              `json:"actual,omitempty"`
}

SchemaViolation is one stable, machine-readable failed graph constraint.

type SchemaViolationCode added in v1.4.0 

type SchemaViolationCode string

SchemaViolationCode identifies the kind of failed schema constraint. 

const (
	SchemaViolationInvalidNode          SchemaViolationCode = "invalid-node"
	SchemaViolationInvalidEdge          SchemaViolationCode = "invalid-edge"
	SchemaViolationNodeID               SchemaViolationCode = "node-id"
	SchemaViolationEdgeID               SchemaViolationCode = "edge-id"
	SchemaViolationNodeLabel            SchemaViolationCode = "node-label"
	SchemaViolationEdgeType             SchemaViolationCode = "edge-type"
	SchemaViolationRequiredProperty     SchemaViolationCode = "required-property"
	SchemaViolationPropertyType         SchemaViolationCode = "property-type"
	SchemaViolationMissingSource        SchemaViolationCode = "missing-source"
	SchemaViolationMissingTarget        SchemaViolationCode = "missing-target"
	SchemaViolationSourceLabel          SchemaViolationCode = "source-label"
	SchemaViolationTargetLabel          SchemaViolationCode = "target-label"
	SchemaViolationSourceCardinalityMin SchemaViolationCode = "source-cardinality-min"
	SchemaViolationSourceCardinalityMax SchemaViolationCode = "source-cardinality-max"
	SchemaViolationTargetCardinalityMin SchemaViolationCode = "target-cardinality-min"
	SchemaViolationTargetCardinalityMax SchemaViolationCode = "target-cardinality-max"
	SchemaViolationNaturalKeyUnique     SchemaViolationCode = "natural-key-unique"
	SchemaViolationAcyclic              SchemaViolationCode = "acyclic"
	SchemaViolationNoSelfLoop           SchemaViolationCode = "no-self-loop"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.