projection

package
v0.1.0-alpha.5 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 12 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 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 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.

A request that is incomplete or outside the contract is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.

func (*MutationClient) Create

Create atomically creates an entity with its complete initial triples.

A request that is incomplete or outside the contract is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.

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.

A zero ExpectedRevision is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.

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.

A read writes nothing, so every failure is not committed, with operation read-authoritative.

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.

It reads the entity first. A failed read sends no mutation and is not committed, with operation read-authoritative; a stored entity outside the contract is refused as MutationInvalid. A request that is incomplete or outside the contract is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.

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 ClassifyMutationError

func ClassifyMutationError(operation MutationOperation, err error) *MutationError

ClassifyMutationError maps the error of one graph mutation request to the commit state it proves, and returns nil for a nil error. It is the one mapping every MutationClient write uses.

The error is not committed in two cases. Its chain holds a classified reply whose code graph-ingest sends only before it writes (invalid request, structural invalid, message type unregistered, entity ID invalid, entity ID authority invalid, revision mismatch, entity exists, entity not found, graph state reset required): the error keeps that reply's class, code and a copy of its detail. Or the request was not delivered, because no responder took it, natsclient refused it before sending (ErrNotConnected), or the caller's context ended before it was sent: Kind MutationUnavailable, class transient.

Every other error, a classified reply with any other code included, is commit-unknown and fatal, so it is never retried: a write that may have committed could apply twice.

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 an operation that could not complete and wrote nothing. For a
	// write, the request was not delivered: no responder took it, or the caller's context ended
	// before it was sent. For a read (operation read-authoritative), the request may have been
	// delivered, but a read stores nothing.
	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
}

MutationReceipt contains the authoritative result of a mutation that committed. A method that fails returns a zero receipt, and its *MutationError's Commit reports what is proven.

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. It is the one type both ends of the rule-pack binding name: service.ProjectionBinder receives it and the rule processor that binds the pack calls it, so neither names *MutationClient.

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 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 (SemStreams ADR-103).
Package contract holds the projection contract data types and their shape validation (SemStreams ADR-103).

Jump to

Keyboard shortcuts

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