projection

package
v0.1.0-alpha.1 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package projection provides a small contract-validating client for graph mutations. Contracts describe operation intent and expected graph shape; they do not grant ownership or prevent other components from writing.

Index

Constants

View Source
const (
	// ModeReconcile declares complete-set predicate reconciliation.
	ModeReconcile = contract.ModeReconcile
	// ModeAppend declares set-valued predicate addition.
	ModeAppend = contract.ModeAppend
)

Variables

View Source
var ErrInvalidContract = contract.ErrInvalidContract

ErrInvalidContract identifies a projection contract rejected before use.

Functions

func ValidateContracts

func ValidateContracts(contracts []Contract) error

ValidateContracts validates a complete, uniquely named contract set.

Types

type AppendMutation

type AppendMutation struct {
	Contract string
	Group    string
	EntityID string
	Triples  []message.Triple
	Metadata MutationMetadata
}

AppendMutation requests set-valued addition to one declared predicate group.

type AuthoritativeReader

type AuthoritativeReader interface {
	ReadAuthoritative(context.Context, string) (*graph.ExactEntity, error)
}

AuthoritativeReader reads entity bytes and their same-entry KV revision.

type CommitState

type CommitState string

CommitState reports what the client can prove about mutation commitment.

const (
	// CommitNotCommitted proves the mutation did not commit.
	CommitNotCommitted CommitState = "not-committed"
	// CommitUnknown reports that the mutation may have committed: it was delivered, and neither
	// its reply nor its absence proves the outcome.
	CommitUnknown CommitState = "unknown"
	// CommitVerified reports a valid authoritative mutation response.
	CommitVerified CommitState = "verified"
)

type Contract

type Contract = contract.Contract

Contract declares the graph shape emitted by one projection. It validates caller intent; it does not reserve predicates or prevent other writers.

type CreateMutation

type CreateMutation struct {
	Contract string
	Entity   *graph.EntityState
	Triples  []message.Triple
	Metadata MutationMetadata
}

CreateMutation requests strict creation of one entity.

type DeleteMutation

type DeleteMutation struct {
	EntityID         string
	ExpectedRevision uint64
	Metadata         MutationMetadata
}

DeleteMutation requests revision-fenced deletion of one entity.

type EntityCreator

type EntityCreator interface {
	Create(context.Context, CreateMutation) (MutationReceipt, error)
}

EntityCreator creates one entity through the canonical mutation port.

type EntityDeleter

type EntityDeleter interface {
	Delete(context.Context, DeleteMutation) (MutationReceipt, error)
}

EntityDeleter deletes one entity at an expected authority revision.

type MutationClient

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

MutationClient is an immutable, concurrency-safe graph mutation client.

func NewMutationClient

func NewMutationClient(cfg MutationClientConfig) (*MutationClient, error)

NewMutationClient validates and copies the complete projection contract set.

func (*MutationClient) Append

Append appends triples in one append-mode predicate group to one entity.

func (*MutationClient) Create

Create atomically creates an entity with its complete initial triples.

func (*MutationClient) Delete

Delete conditionally deletes one entity. Callers supply the exact revision they intend to fence; the client does not hide a read or retry.

func (*MutationClient) ReadAuthoritative

func (c *MutationClient) ReadAuthoritative(ctx context.Context, entityID string) (*graph.ExactEntity, error)

ReadAuthoritative returns one validated entity and its same-entry revision.

func (*MutationClient) Reconcile

func (c *MutationClient) Reconcile(ctx context.Context, request ReconcileMutation) (MutationReceipt, error)

Reconcile replaces one complete reconcile-mode predicate group, at the request's ExpectedRevision or, when that is zero, at the revision the client reads.

type MutationClientConfig

type MutationClientConfig struct {
	NATS      *natsclient.Client
	Contracts []Contract
	Timeout   time.Duration
}

MutationClientConfig configures one immutable contract-validating client.

type MutationError

type MutationError struct {
	Operation MutationOperation
	Kind      MutationErrorKind
	Code      string
	Class     errs.ErrorClass
	Commit    CommitState
	Detail    map[string]any
	Err       error
}

MutationError preserves operation, classification, and commitment evidence.

func (*MutationError) Error

func (e *MutationError) Error() string

func (*MutationError) Unwrap

func (e *MutationError) Unwrap() error

type MutationErrorKind

type MutationErrorKind string

MutationErrorKind is the stable caller-facing mutation failure category.

const (
	// MutationInvalid reports a request rejected before mutation.
	MutationInvalid MutationErrorKind = "invalid"
	// MutationNotFound reports a required entity that does not exist.
	MutationNotFound MutationErrorKind = "not-found"
	// MutationConflict reports strict-create or semantic conflict.
	MutationConflict MutationErrorKind = "conflict"
	// MutationRevisionConflict reports a stale expected authority revision.
	MutationRevisionConflict MutationErrorKind = "revision-conflict"
	// MutationUnavailable reports no available mutation responder.
	MutationUnavailable MutationErrorKind = "unavailable"
	// MutationCommitUnknown reports a mutation that may have committed (CommitUnknown).
	MutationCommitUnknown MutationErrorKind = "commit-unknown"
	// MutationInternal reports an unclassified framework failure.
	MutationInternal MutationErrorKind = "internal"
)

type MutationMetadata

type MutationMetadata struct {
	RequestID string
	TraceID   string
	Source    string
	Timestamp time.Time
}

MutationMetadata carries correlation and triple provenance. Create and Append require RequestID and Source; Reconcile requires Source and sends it as the request's source. Every statement of a Create, Append or Reconcile needs a Timestamp, its own or this one: the client never reads the clock. A caller retrying one logical Create or Append must set Timestamp once and reuse the complete Metadata; regenerating it would change tuple identity. Other fields remain operation-specific.

type MutationOperation

type MutationOperation string

MutationOperation identifies the client operation that produced a result.

const (
	// MutationOperationCreate identifies strict entity creation.
	MutationOperationCreate MutationOperation = "create"
	// MutationOperationReconcile identifies predicate-set reconciliation.
	MutationOperationReconcile MutationOperation = "reconcile"
	// MutationOperationAppend identifies set-valued triple addition.
	MutationOperationAppend MutationOperation = "append"
	// MutationOperationDelete identifies revision-fenced entity deletion.
	MutationOperationDelete MutationOperation = "delete"
	// MutationOperationReadAuthoritative identifies an exact authority read.
	MutationOperationReadAuthoritative MutationOperation = "read-authoritative"
)

type MutationReceipt

type MutationReceipt struct {
	Entity     *graph.EntityState
	KVRevision uint64
	Commit     CommitState
}

MutationReceipt contains the authoritative result and commitment evidence.

type PredicateGroup

type PredicateGroup = contract.PredicateGroup

PredicateGroup names predicates changed together through one operation.

type PredicateReconciler

type PredicateReconciler interface {
	Reconcile(context.Context, ReconcileMutation) (MutationReceipt, error)
}

PredicateReconciler reconciles one declared predicate group.

type ReconcileMutation

type ReconcileMutation struct {
	Contract string
	Group    string
	EntityID string
	// ExpectedRevision is the entity's revision the caller read. graph-ingest applies the
	// reconcile only while the entity is still at that revision, and otherwise refuses it with a
	// revision conflict and changes nothing. Zero means the caller names no revision: the client
	// fences at the revision of its own read, so a write between the caller's read and the
	// client's goes undetected.
	ExpectedRevision uint64
	Desired          []message.Triple
	Metadata         MutationMetadata
}

ReconcileMutation requests replacement of one declared predicate group.

type TripleAppender

type TripleAppender interface {
	Append(context.Context, AppendMutation) (MutationReceipt, error)
}

TripleAppender appends set-valued triples to an existing entity.

type WriteMode

type WriteMode = contract.WriteMode

WriteMode states whether a predicate group is replaced as a complete set or appended as evidence. It is operation intent, not semantic ownership.

Directories

Path Synopsis
Package contract holds the projection contract data types and their shape validation (ADR-103).
Package contract holds the projection contract data types and their shape validation (ADR-103).

Jump to

Keyboard shortcuts

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