mutation

Documentation

Overview

Package mutation defines the application-neutral MALT mutation and receipt contracts. The package contains value types and validation only; applying a mutation, choosing a materialization namespace, and publishing a result root belong to an execution backend.

Index

• Constants
• Variables
• func Validate(mut SemanticMutation) error
• type ArcSetDelta
• type ClientRootBundle
  • func NewClientRootBundle(bundle ClientRootBundle) (ClientRootBundle, error)
  • func (b ClientRootBundle) Digest() ([32]byte, error)
• type ClientRootMaterialization
  • func NewClientRootMaterialization(bundle ClientRootBundle, value ClientRootMaterialization) (ClientRootMaterialization, error)
• type CommitDescriptor
• type FixedListCommit
• type IntentChange
• type IntentTransition
• type MapMaterialization
• type MapStateMaterialization
• type MaterializationReceipt
  • func (r MaterializationReceipt) Validate(bundle ClientRootBundle) error
• type SemanticIntent
  • func NormalizeSemanticIntent(view UpdateView, intent SemanticIntent) (SemanticIntent, error)
  • func (i SemanticIntent) Digest() ([32]byte, error)
• type SemanticMutation
• type TransitionOutput
• type UpdateObject
• type UpdateView
  • func NormalizeUpdateView(view UpdateView) (UpdateView, error)
  • func (v UpdateView) Digest() ([32]byte, error)
• type UpdateViewBounds
• type WriteReceipt

Constants

const (
	UpdateViewProfile              = "malt.update-view/v1"
	SemanticIntentProfile          = "malt.semantic-intent/v1"
	ClientRootBundleProfile        = "malt.client-root-bundle/v1"
	MaterializationReceiptProfile  = "malt.materialization-receipt/v1"
	StatefulCompleteVectorsProfile = "stateful-complete-vectors-v1"
)

const ClientRootMaterializationProfile = "malt.client-root-materialization/v1"

Variables

var (
	ErrInvalidUpdateView       = errors.New("invalid update view")
	ErrIncompleteUpdateView    = errors.New("incomplete update view")
	ErrUpdateViewCycle         = errors.New("update view cycle")
	ErrInvalidSemanticIntent   = errors.New("invalid semantic intent")
	ErrIntentDependencyCycle   = errors.New("intent dependency cycle")
	ErrIntentMultiplicity      = errors.New("intent output multiplicity mismatch")
	ErrInvalidClientRootBundle = errors.New("invalid client root bundle")
	ErrBundleDigestMismatch    = errors.New("client root bundle digest mismatch")
	ErrBundleCandidateMismatch = errors.New("client root candidate mismatch")
)

var (
	// ErrInvalidBaseRoot is returned when an update mutation has no base root.
	ErrInvalidBaseRoot = errors.New("invalid base root")
	// ErrEmptyDeltas is returned when a semantic mutation carries no arc deltas.
	ErrEmptyDeltas = errors.New("empty deltas")
	// ErrObjectKindMismatch is returned when a delta kind disagrees with its object or changes kind.
	ErrObjectKindMismatch = errors.New("object kind mismatch")
	// ErrNilDelta is returned when a mutation has no canonical delta.
	ErrNilDelta = errors.New("nil delta")
	// ErrExpectedRootMismatch is returned when an executor does not reproduce
	// the result root declared by a mutation plan.
	ErrExpectedRootMismatch = errors.New("expected root mismatch")
)

Functions

func Validate

func Validate(mut SemanticMutation) error

Validate validates the portable shape of a semantic mutation.

Types

type ArcSetDelta

type ArcSetDelta struct {
	Object       cid.Cid
	ExpectedRoot cid.Cid
	Kind         arcset.Kind
	Changes      *arcset.CanonicalArcDelta
	Commit       CommitDescriptor
}

ArcSetDelta applies coordinate-level changes to one semantic object.

type ClientRootBundle

type ClientRootBundle struct {
	Profile      string
	OperationID  string
	View         UpdateView
	Intent       SemanticIntent
	Outputs      []TransitionOutput
	Candidate    cid.Cid
	PayloadCIDs  []cid.Cid
	ViewDigest   [32]byte
	IntentDigest [32]byte
}

ClientRootBundle is the exact-root submission. It binds the complete view, normalized intent, every intermediate root, referenced payloads, and the designated candidate. A Gateway may accept this candidate or reject it; it must not substitute a different root.

func NewClientRootBundle

func NewClientRootBundle(bundle ClientRootBundle) (ClientRootBundle, error)

NewClientRootBundle validates and canonicalizes one exact-root submission.

func (ClientRootBundle) Digest

func (b ClientRootBundle) Digest() ([32]byte, error)

Digest returns the deterministic SHA-256 digest of a canonical bundle.

type ClientRootMaterialization

type ClientRootMaterialization struct {
	Profile string
	Base    *MapStateMaterialization
	Maps    []MapMaterialization
}

ClientRootMaterialization carries root-bound proof-serving witnesses for every map output in one exact client-root bundle. List outputs are omitted until their tree materialization receives an equivalent witness profile.

func NewClientRootMaterialization

func NewClientRootMaterialization(bundle ClientRootBundle, value ClientRootMaterialization) (ClientRootMaterialization, error)

NewClientRootMaterialization validates and canonicalizes one witness against the exact transition/output identities in bundle.

type CommitDescriptor

type CommitDescriptor struct {
	FixedList *FixedListCommit
}

CommitDescriptor records how a logical canonical arcset should be committed into a concrete semantic root. The zero value is the default map/list commit.

type FixedListCommit

type FixedListCommit struct {
	TotalSize uint64
	ChunkSize uint64
}

FixedListCommit describes the measured fixed-width list commit profile.

type IntentChange

type IntentChange struct {
	Coordinate arcset.CanonicalCoordinate
	Before     *arcset.TargetRef
	After      *arcset.TargetRef
	OutputID   string
	OutputKind arcset.TargetKind
}

IntentChange selects either a literal post-image target or the output of a child transition. A nil After and empty OutputID is a deletion. Exactly one of After and OutputID may be present.

type IntentTransition

type IntentTransition struct {
	ID           string
	ObjectID     string
	OldRoot      cid.Cid
	Kind         arcset.Kind
	Backend      maltcid.BackendKind
	Changes      []IntentChange
	Commit       CommitDescriptor
	ExpectedUses uint32
}

IntentTransition describes one object update. OldRoot may be undefined only for a newly-created object. ExpectedUses declares how many parent coordinates consume this transition's output; the designated top output has zero uses.

type MapMaterialization

type MapMaterialization struct {
	TransitionID string
	Root         cid.Cid
	Entries      *arcset.CanonicalArcSet
}

MapMaterialization carries the exact internal proof-serving state for one map transition output. Entries are implementation-owned radix cache paths, not logical map coordinates.

type MapStateMaterialization

type MapStateMaterialization struct {
	Root    cid.Cid
	Entries *arcset.CanonicalArcSet
}

MapStateMaterialization carries root-bound proof-serving state for the complete map base included in a bootstrap writer result.

type MaterializationReceipt

type MaterializationReceipt struct {
	Profile         string
	OperationID     string
	BaseRoot        cid.Cid
	Candidate       cid.Cid
	BundleDigest    [32]byte
	DurableBoundary string
}

MaterializationReceipt is a durable acknowledgement of one exact bundle. Publication and client trust acceptance remain separate policies.

func (MaterializationReceipt) Validate

func (r MaterializationReceipt) Validate(bundle ClientRootBundle) error

Validate checks a durable receipt against the exact submitted bundle.

type SemanticIntent

type SemanticIntent struct {
	Profile     string
	BaseRoot    cid.Cid
	Transitions []IntentTransition
	TopOutputID string
}

SemanticIntent is output-free: child results are referenced by transition ID and no candidate root is supplied until local computation finishes.

func NormalizeSemanticIntent

func NormalizeSemanticIntent(view UpdateView, intent SemanticIntent) (SemanticIntent, error)

NormalizeSemanticIntent validates an output-free intent against the complete update view and returns child-before-parent deterministic order.

func (SemanticIntent) Digest

func (i SemanticIntent) Digest() ([32]byte, error)

Digest returns the deterministic SHA-256 digest of a normalized intent.

type SemanticMutation

type SemanticMutation struct {
	BaseRoot cid.Cid
	Deltas   []ArcSetDelta
}

SemanticMutation is the portable mutation boundary emitted by clients and application adapters. It deliberately carries no namespace, tenant, storage, or publication policy.

type TransitionOutput

type TransitionOutput struct {
	TransitionID string
	Root         cid.Cid
}

TransitionOutput binds one normalized transition to the exact root computed locally. Outputs are ordered by transition ID in a client-root bundle.

type UpdateObject

type UpdateObject struct {
	ObjectID string
	Root     cid.Cid
	Kind     arcset.Kind
	Entries  *arcset.CanonicalArcSet
	Commit   CommitDescriptor
}

UpdateObject binds a stable operation-local ID to one complete canonical logical vector and its current typed semantic root.

type UpdateView

type UpdateView struct {
	Profile      string
	StateProfile string
	BaseRoot     cid.Cid
	Bounds       UpdateViewBounds
	Objects      []UpdateObject
}

UpdateView is the complete old semantic closure needed to verify and update one accepted root locally. Objects are ordered by ObjectID in canonical form. Every typed MALT child reachable from BaseRoot must occur exactly once; unrelated objects are rejected.

func NormalizeUpdateView

func NormalizeUpdateView(view UpdateView) (UpdateView, error)

NormalizeUpdateView validates a view and returns a deep canonical copy.

func (UpdateView) Digest

func (v UpdateView) Digest() ([32]byte, error)

Digest returns the deterministic SHA-256 digest of a canonical update view.

type UpdateViewBounds

type UpdateViewBounds struct {
	MaxObjects      uint32
	MaxTotalEntries uint64
	MaxDepth        uint32
}

UpdateViewBounds is part of the authenticated client-writer request. It prevents an untrusted service from expanding a small mutation into an unbounded state download.

type WriteReceipt

type WriteReceipt struct {
	BaseRoot   cid.Cid
	NewRoot    cid.Cid
	DeltaCount int
	ArcCount   int
}

WriteReceipt records the execution result without publishing or authorizing the returned root.