graphmutation

package
v0.1.0-alpha.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package graphmutation owns the in-repository graph mutation protocol identity. Application callers use narrow typed clients rather than subjects directly. ClassifyPort decides whether a component port is a graph-mutation port and whether it has the valid shape; flowgraph and graph-ingest both call it.

Index

Constants

View Source
const (
	// InterfaceType is the canonical component-port interface identity.
	InterfaceType = "semengine.graph.mutation"
	// InterfaceVersion is the canonical component-port interface version.
	InterfaceVersion = "v1"
	// SubjectFamily is the only admitted NATS request/reply subject family.
	SubjectFamily = "graph.mutation.>"
)

Variables

This section is empty.

Functions

func ClassifyPort

func ClassifyPort(facts component.PortFacts, required bool) (member, valid bool)

ClassifyPort decides, for one component port, whether it is a graph-mutation port (member) and whether it has the one valid shape (valid). required is the port's Required flag, which PortFacts does not carry.

A port is a member when its interface type is InterfaceType, or when any one of its NATS subjects starts with the family's prefix, graph.mutation., whatever the port's kind (owner ruling, #323 comment 6279624359). A member is valid when it is a required nats-request port whose subjects are exactly SubjectFamily and whose interface is InterfaceType at InterfaceVersion. valid implies member.

Flowgraph and graph-ingest both call it; each keeps its own direction rule, provider count and refusal text.

func IsDefinitelyNotCommitted

func IsDefinitelyNotCommitted(err error) bool

IsDefinitelyNotCommitted reports transport outcomes that prove no request was delivered: no request was sent, or no responder took it, or the context was already done before the call.

func Subject

func Subject(operation Operation) (string, error)

Subject returns the exact subject for an admitted operation within SubjectFamily. It rejects every other operation; callers cannot fall back to a port name or a literal subject table.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the single in-repository adapter for the canonical mutation port. Each method makes exactly one request. It never retries an ambiguous delivery.

func NewClient

func NewClient(requester requester, timeout time.Duration) (*Client, error)

NewClient binds the canonical mutation protocol to a request/reply client.

func (*Client) Append

Append appends triples independently per distinct subject.

func (*Client) Create

Create performs one atomic entity birth request. A request without an entity is refused before sending.

func (*Client) Delete

Delete conditionally deletes one entity at the supplied authority revision.

func (*Client) Reconcile

Reconcile makes one predicate set equal the supplied desired set.

type Operation

type Operation string

Operation identifies one admitted graph mutation command.

const (
	// CreateEntity strictly creates one entity and rejects an existing ID.
	CreateEntity Operation = "entity.create"
	// ReconcilePredicates replaces a declared predicate set under a revision fence.
	ReconcilePredicates Operation = "entity.reconcile"
	// AppendTriples adds set-valued triples to existing subjects.
	AppendTriples Operation = "triple.append"
	// DeleteEntity removes one entity under a revision fence.
	DeleteEntity Operation = "entity.delete"
)

type TransportError

type TransportError struct {
	Operation Operation
	Outcome   TransportOutcome
	Err       error
}

TransportError is returned only for transport or invalid-reply failures. Classified handler failures remain their original typed error.

func (*TransportError) Error

func (e *TransportError) Error() string

func (*TransportError) Unwrap

func (e *TransportError) Unwrap() error

type TransportOutcome

type TransportOutcome string

TransportOutcome describes what the requester can prove when no valid mutation reply exists. Only CommitUnknown permits that the command may have reached graph-ingest.

const (
	// TransportUnavailable proves that no request was sent, or no responder took it:
	// natsclient refused it before sending (ErrNotConnected), or no
	// mutation responder accepted it.
	TransportUnavailable TransportOutcome = "unavailable"
	// TransportDeadline proves the context ended before request delivery.
	TransportDeadline TransportOutcome = "deadline"
	// TransportCommitUnknown reports delivery without a valid mutation reply.
	TransportCommitUnknown TransportOutcome = "commit_unknown"
)

Jump to

Keyboard shortcuts

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