graphcontract

package
v1.5.0 Latest Latest
Warning

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

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

Documentation

Overview

Package graphcontract defines Spool's canonical graph object contract.

Index

Constants

View Source 
const (
	// PackMagic identifies an IDG pack stream.
	PackMagic = "IDGP"
	// PackFormatVersion is the version encoded in every pack header.
	PackFormatVersion uint32 = 2
	// PackIndexFormatVersion is the version of the sidecar object index.
	PackIndexFormatVersion uint32 = 1
	// PackManifestFormatVersion is the version of objects/info/packs.
	PackManifestFormatVersion uint32 = 1
	// PackHeaderSize is the fixed byte length of a pack stream header.
	PackHeaderSize = 12
	// MaxPackIDLength is the longest pack ID a verifier accepts.
	MaxPackIDLength = 64
)
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 (
	// ErrPackCorrupt reports malformed or inconsistent pack, index, or manifest data.
	ErrPackCorrupt = errors.New("pack storage is corrupt")
	// ErrUnsupportedPackVersion reports a pack storage format newer or older than this repository supports.
	ErrUnsupportedPackVersion = errors.New("unsupported pack storage version")
)
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 DecodePackedObjectEnvelope added in v1.5.0 

func DecodePackedObjectEnvelope(data []byte, id ObjectID) (objectType string, objectData []byte, err error)

DecodePackedObjectEnvelope decodes and fully verifies one packed object envelope: it must decode as canonical CBOR, carry a non-empty type, and hash to id under ObjectIDForEncoded. It returns the object's type and a defensive copy of its canonical bytes.

func DecompressPackedObject added in v1.5.0 

func DecompressPackedObject(entry PackIndexEntry, compressed []byte) (objectType string, objectData []byte, err error)

DecompressPackedObject validates a packed entry's CRC32, decompresses its zstd-compressed envelope, verifies the decompressed size, and decodes and verifies its canonical object envelope. It returns the object's type and canonical bytes. Decompression is streamed and bounded to entry.UncompressedSize+1 bytes so a corrupt or hostile entry cannot force unbounded memory allocation before the size check runs.

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 MarshalSnapshot added in v1.5.0 

func MarshalSnapshot(s Snapshot) ([]byte, error)

MarshalSnapshot returns the normalized, canonical CBOR encoding of s.

func MergeConflictID added in v1.5.0 

func MergeConflictID(conflict MergeConflict) (string, error)

MergeConflictID returns the deterministic content-derived identifier for one merge conflict using the canonical merge-conflict object encoding.

func MergeConflictPaths added in v1.5.0 

func MergeConflictPaths(conflict MergeConflict) []string

MergeConflictPaths returns the deterministic graph path list for one merge conflict when the conflict did not already provide explicit paths.

func SchemaViolationPaths added in v1.5.0 

func SchemaViolationPaths(violation SchemaViolation) []string

SchemaViolationPaths returns the deterministic graph path list that identifies a schema validation failure.

func SortMergeConflicts added in v1.5.0 

func SortMergeConflicts(conflicts []MergeConflict)

SortMergeConflicts orders merge conflicts deterministically by category, entity, entity ID, field, and then path list contents.

func ValidPackID added in v1.5.0 

func ValidPackID(id PackID) bool

ValidPackID reports whether id is a well-formed 32-character lowercase hex pack identifier.

func ValidatePackEntries added in v1.5.0 

func ValidatePackEntries(packID PackID, header PackHeader, packSize uint64, entries []PackIndexEntry) error

ValidatePackEntries checks that a pack's header agrees with its enumerated index entries and that the entries form one contiguous, non-overlapping region spanning exactly [PackHeaderSize, packSize) when ordered by offset. Callers must pass entries already validated by ValidatePackIndexEntry and sorted by ascending Offset.

func ValidatePackHeader added in v1.5.0 

func ValidatePackHeader(header PackHeader) error

ValidatePackHeader checks a decoded pack header's magic and format version.

func ValidatePackIndexEntry added in v1.5.0 

func ValidatePackIndexEntry(packID PackID, entry PackIndexEntry) error

ValidatePackIndexEntry checks that entry's object ID is well-formed and its offset and size fields describe a region that cannot overflow a pack stream's addressable bounds.

func ValidatePackIndexMetadata added in v1.5.0 

func ValidatePackIndexMetadata(metadata PackIndexMetadata) error

ValidatePackIndexMetadata checks a decoded pack index's format version and pack ID before any of its entries are trusted.

func ValidatePackManifest added in v1.5.0 

func ValidatePackManifest(manifest PackManifest) error

ValidatePackManifest checks a decoded pack manifest's format version and every listed pack's ID, version, and compression.

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 MergeChange added in v1.5.0 

type MergeChange struct {
	Entity string `json:"entity"`
	ID     string `json:"id"`
	Change string `json:"change"`
}

MergeChange describes an entity changed from the target snapshot by a merge.

type MergeConflict added in v1.5.0 

type MergeConflict struct {
	// ConflictID is the deterministic identifier used when selecting a resolution.
	ConflictID string `json:"conflictId"`
	// Category is "structural", "schema", or "semantic".
	Category string `json:"category"`
	// Entity is "node", "edge", or "schema".
	Entity string `json:"entity"`
	// ID identifies the affected graph entity when applicable.
	ID string `json:"id,omitempty"`
	// Field identifies the overlapping field or property key.
	Field string `json:"field,omitempty"`
	// Paths identifies the affected graph locations in deterministic order.
	Paths []string `json:"paths"`
}

MergeConflict describes one deterministic three-way merge disagreement.

type MergeResult added in v1.5.0 

type MergeResult struct {
	Nodes      map[string]Node
	Edges      map[string]Edge
	SchemaRoot ObjectID
	Clean      bool
	Changes    []MergeChange
	Conflicts  []MergeConflict
	Violations []SchemaViolation
}

MergeResult is the deterministic outcome of a three-way graph merge simulation.

func ThreeWayMerge added in v1.5.0 

func ThreeWayMerge(
	baseNodes, sourceNodes, targetNodes map[string]Node,
	baseEdges, sourceEdges, targetEdges map[string]Edge,
	baseSchemaRoot, sourceSchemaRoot, targetSchemaRoot ObjectID,
) (MergeResult, error)

ThreeWayMerge computes a deterministic three-way merge of graph nodes, edges, and schema roots against a common base keyed by canonical object ID. It reports structural and schema-root conflicts only; callers that can resolve SchemaRoot to a schema snapshot may perform validation afterward and append semantic conflicts and violations deterministically.

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.

func ObjectIDForEncoded added in v1.5.0 

func ObjectIDForEncoded(objectType string, encoded []byte) ObjectID

ObjectIDForEncoded computes the content-derived ObjectID for encoded bytes of the given object type, using the BLAKE3-based scheme shared by loose and packed object storage.

type PackCompression added in v1.5.0 

type PackCompression string

PackCompression identifies the compression applied to a packed object envelope. 

const (
	// PackCompressionZstd is the required compression for PackFormatVersion.
	PackCompressionZstd PackCompression = "zstd"
)

type PackCorruptionError added in v1.5.0 

type PackCorruptionError struct {
	Pack   PackID
	Object ObjectID
	Offset uint64
	Detail string
}

PackCorruptionError identifies a failed pack, index, or manifest validation. Object and Offset are omitted when corruption is not associated with an entry.

func (*PackCorruptionError) Error added in v1.5.0 

func (e *PackCorruptionError) Error() string

Error implements error.

func (*PackCorruptionError) Unwrap added in v1.5.0 

func (e *PackCorruptionError) Unwrap() error

Unwrap makes PackCorruptionError match ErrPackCorrupt.

type PackHeader added in v1.5.0 

type PackHeader struct {
	Magic       [4]byte
	Version     uint32
	ObjectCount uint32
}

PackHeader is the fixed 12-byte, big-endian prefix of every pack stream. Magic must equal PackMagic and Version must equal PackFormatVersion before any object entry is processed.

func ReadPackHeader added in v1.5.0 

func ReadPackHeader(reader io.Reader) (PackHeader, error)

ReadPackHeader decodes the fixed-size pack header from the start of reader without validating its contents. Use ValidatePackHeader to check the result.

func ReadPackHeaderAt added in v1.5.0 

func ReadPackHeaderAt(reader io.ReaderAt) (PackHeader, error)

ReadPackHeaderAt decodes the fixed-size pack header at the start of reader without validating its contents. Use ValidatePackHeader to check the result.

type PackID added in v1.5.0 

type PackID string

PackID identifies one immutable pack and its paired index.

type PackIndexEntry added in v1.5.0 

type PackIndexEntry struct {
	Object           ObjectID `json:"object"`
	Offset           uint64   `json:"offset"`
	CompressedSize   uint64   `json:"compressedSize"`
	UncompressedSize uint64   `json:"uncompressedSize"`
	CRC32            uint32   `json:"crc32"`
}

PackIndexEntry maps one object ID to its zstd-compressed canonical loose envelope in a pack. CRC32 is the IEEE CRC32 of the compressed bytes.

type PackIndexMetadata added in v1.5.0 

type PackIndexMetadata struct {
	Version     uint32
	Pack        PackID
	ObjectCount uint32
}

PackIndexMetadata is persisted by a pack-index implementation and binds the index to one pack before any entry lookup is trusted.

type PackManifest added in v1.5.0 

type PackManifest struct {
	Version uint32         `json:"version"`
	Packs   []PackMetadata `json:"packs"`
}

PackManifest is the atomically replaced list of active packs.

type PackMetadata added in v1.5.0 

type PackMetadata struct {
	ID          PackID          `json:"id"`
	Version     uint32          `json:"version"`
	Compression PackCompression `json:"compression"`
	ObjectCount uint32          `json:"objectCount"`
}

PackMetadata identifies an active pack listed by a manifest.

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"
)

type Snapshot added in v1.5.0 

type Snapshot struct {
	// NodeRoot identifies the durable root of the snapshot's node projection.
	NodeRoot ObjectID `json:"nodeRoot" cbor:"1,keyasint"`
	// EdgeRoot identifies the durable root of the snapshot's edge projection.
	EdgeRoot ObjectID `json:"edgeRoot" cbor:"2,keyasint"`
	// OutAdjRoot identifies the durable root of the outgoing adjacency projection.
	OutAdjRoot ObjectID `json:"outAdjRoot" cbor:"3,keyasint"`
	// InAdjRoot identifies the durable root of the incoming adjacency projection.
	InAdjRoot ObjectID `json:"inAdjRoot" cbor:"4,keyasint"`
	// SchemaRoot identifies the schema used to validate the snapshot's graph.
	SchemaRoot ObjectID `json:"schemaRoot" cbor:"5,keyasint"`
	// NodeCount is the number of nodes reachable from NodeRoot.
	NodeCount uint64 `json:"nodeCount" cbor:"6,keyasint"`
	// EdgeCount is the number of edges reachable from EdgeRoot.
	EdgeCount uint64 `json:"edgeCount" cbor:"7,keyasint"`
}

Snapshot is the immutable, content-addressed root set for one graph version: the node, edge, incoming-adjacency, outgoing-adjacency, and schema tree roots, plus their entity counts.

func NewSnapshot added in v1.5.0 

func NewSnapshot(nodeRoot, edgeRoot, outAdjRoot, inAdjRoot, schemaRoot ObjectID, nodeCount, edgeCount uint64) (Snapshot, error)

NewSnapshot constructs a normalized snapshot root record.

func UnmarshalSnapshot added in v1.5.0 

func UnmarshalSnapshot(data []byte) (Snapshot, error)

UnmarshalSnapshot decodes and verifies canonical CBOR for a snapshot root record.

func (Snapshot) Clone added in v1.5.0 

func (s Snapshot) Clone() Snapshot

Clone returns a copy of s. Snapshot has no reference fields, so Clone returns s by value.

func (Snapshot) Equal added in v1.5.0 

func (s Snapshot) Equal(other Snapshot) bool

Equal reports semantic equality after canonical normalization.

func (Snapshot) MarshalCBOR added in v1.5.0 

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

MarshalCBOR returns the normalized, canonical CBOR encoding of s.

func (Snapshot) Normalize added in v1.5.0 

func (s Snapshot) Normalize() (Snapshot, error)

Normalize returns the canonical snapshot representation. Snapshot has no collections to sort or deduplicate; normalization is a defensive copy.

func (*Snapshot) UnmarshalCBOR added in v1.5.0 

func (s *Snapshot) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes and verifies canonical CBOR for s.

type UnsupportedPackVersionError added in v1.5.0 

type UnsupportedPackVersionError struct {
	Format  string
	Version uint32
}

UnsupportedPackVersionError identifies a pack, index, or manifest format this repository cannot safely read.

func (*UnsupportedPackVersionError) Error added in v1.5.0 

func (e *UnsupportedPackVersionError) Error() string

Error implements error.

func (*UnsupportedPackVersionError) Unwrap added in v1.5.0 

func (e *UnsupportedPackVersionError) Unwrap() error

Unwrap makes UnsupportedPackVersionError match ErrUnsupportedPackVersion.

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.