workspace

type ApplyDecision ¶

type ApplyDecision string

ApplyDecision is the caller-side durable outcome of applying one exact Artifact. Indeterminate is terminal: reconciliation requires a new Task and Artifact rather than replaying a possibly completed external side effect.

const (
	ApplySuccess       ApplyDecision = "success"
	ApplyConflict      ApplyDecision = "conflict"
	ApplyRejected      ApplyDecision = "rejected"
	ApplyIndeterminate ApplyDecision = "indeterminate"
)

func (decision ApplyDecision) Valid() bool

type ApplyIdentity ¶

type ApplyIdentity struct {
	Authority string `json:"authority"`
	Workspace string `json:"workspace"`
	Artifact  string `json:"artifact"`
}

ApplyIdentity is the caller-side idempotency key for applying one immutable Artifact. Authority prevents identities issued by independent security domains from colliding; Workspace identifies the revision chain; Artifact is the immutable object being applied to that chain.

type ApplyIntent ¶

type ApplyIntent struct {
	Identity       ApplyIdentity `json:"identity"`
	ArtifactDigest Digest        `json:"artifact_digest"`
	PayloadDigest  Digest        `json:"payload_digest"`
	BaseRevision   Revision      `json:"base_revision"`
	ResultRevision Revision      `json:"result_revision"`
	Payload        Payload       `json:"payload"`
}

ApplyIntent is the complete, transport-neutral input to one caller-side CAS. Every field participates in exact-retry comparison. Payload is declarative data; an applier must not infer permission to execute it.

func CloneApplyIntent(intent ApplyIntent) ApplyIntent

type ApplyRecord ¶

type ApplyRecord struct {
	Intent       ApplyIntent `json:"intent"`
	IntentDigest Digest      `json:"intent_digest"`
	State        ApplyState  `json:"state"`
	Outcome      *CASOutcome `json:"outcome,omitempty"`
	CreatedAt    time.Time   `json:"created_at"`
	CompletedAt  *time.Time  `json:"completed_at,omitempty"`
}

ApplyRecord is the durable caller-side evidence for an Artifact apply. A pending record has a nil Outcome and CompletedAt. Every terminal record has both. IntentDigest protects the exact canonical Intent bytes at rest.

func CloneApplyRecord(record ApplyRecord) ApplyRecord

type ApplyResult ¶

type ApplyResult struct {
	Record ApplyRecord `json:"record"`
	Replay bool        `json:"replay"`
}

ApplyResult reports whether this call performed the external CAS or replayed a previously durable terminal record.

type ApplyState ¶

type ApplyState string

ApplyState is the durable lifecycle of one apply intent. Pending is never safe to execute after a process boundary: a Store implementation must reconcile a recovered pending record as indeterminate without invoking the external CAS again.

const (
	ApplyStatePending       ApplyState = "pending"
	ApplyStateSuccess       ApplyState = "success"
	ApplyStateConflict      ApplyState = "conflict"
	ApplyStateRejected      ApplyState = "rejected"
	ApplyStateIndeterminate ApplyState = "indeterminate"
)

func (state ApplyState) Terminal() bool

type CASApplier ¶

type CASApplier interface {
	ApplyCAS(context.Context, ApplyIntent) (CASOutcome, error)
}

CASApplier owns the external compare-and-swap boundary. ApplyCAS may change state before returning, so every returned error is treated as an unknown external outcome and durably recorded as ApplyIndeterminate. A callback may call Lookup, but must not synchronously release the Store's owning Resource or recursively Apply the same identity: both operations would wait for the callback itself.

type CASApplierFunc ¶

type CASApplierFunc func(context.Context, ApplyIntent) (CASOutcome, error)

CASApplierFunc makes a function usable as a CASApplier.

func (function CASApplierFunc) ApplyCAS(ctx context.Context, intent ApplyIntent) (CASOutcome, error)

type CASOutcome ¶

type CASOutcome struct {
	Decision         ApplyDecision `json:"decision"`
	ObservedRevision Revision      `json:"observed_revision,omitempty"`
	Code             string        `json:"code,omitempty"`
	Message          string        `json:"message,omitempty"`
}

CASOutcome is the externally observed result of applying an Artifact. A success is valid only when ObservedRevision is exactly the intended result. Indeterminate is terminal and must be reconciled with a new Artifact rather than by replaying this intent.

func CloneCASOutcome(outcome CASOutcome) CASOutcome

func IndeterminateOutcome(code, message string) CASOutcome

type Digest ¶

type Digest string

Digest is a content identity in algorithm:value form.

func CanonicalApplyIntent(intent ApplyIntent) ([]byte, Digest, error)

func DigestPayload(payload Payload) Digest

type Payload ¶

type Payload struct {
	MediaType string `json:"media_type"`
	Data      []byte `json:"data"`
}

Payload is a declarative workspace artifact. Consumers must treat Data as data, never as an implicit command to execute; this value type does not enforce a media-type allowlist. Executable effects need their own authorized, idempotent protocol.

type Revision ¶

type Revision string

Revision is an opaque workspace chain identity. Implementations compare it for exact equality; they must not infer ordering from its contents.

type Store ¶

type Store interface {
	// Description returns static, non-secret implementation metadata. It must be
	// safe before and after resource release and must not perform storage I/O.
	Description() StoreDescription
	// Apply requires a non-nil context, a valid complete intent, and a non-nil
	// applier. Invalid input matches ErrInvalidApply and cannot persist or invoke
	// CAS. A context canceled before durable intent admission cannot invoke CAS;
	// cancellation after admission follows the indeterminate rules above.
	Apply(context.Context, ApplyIntent, CASApplier) (ApplyResult, error)
	// Lookup requires a non-nil context and valid identity. Absence matches
	// ErrApplyNotFound. Every returned byte slice and pointer belongs to the caller.
	Lookup(context.Context, ApplyIdentity) (ApplyRecord, error)
}

Store is the replaceable caller-side workspace durability port. Implementations must be safe for concurrent Apply and Lookup calls and must isolate mutable byte slices returned to or received from callers.

Apply must durably record the exact canonical intent before invoking CAS. An exact concurrent or later retry invokes CAS at most once and replays the terminal record; reuse of an ApplyIdentity with different canonical input returns ErrApplyIntentConflict without invoking CAS. Once CAS has been invoked, any callback error, invalid callback result, lost terminal commit, or recovered pending record is terminally indeterminate and must never cause automatic CAS replay. Store implementations can use CanonicalApplyIntent, ValidateCASOutcome, IndeterminateOutcome, and the Clone functions below to preserve these cross-adapter semantics.

Lifecycle is deliberately not part of this business port: a Human composition releases an explicitly owned Store through framework.Resource, while an injected Store remains caller-owned.

type StoreDescription ¶

type StoreDescription struct {
	Contract framework.Contract
	Provider string
	Version  string
}

StoreDescription is static, non-secret implementation metadata. Provider identifies the adapter (for example "sqlite" or a Go module path); Version is the adapter release or schema family, not a database address.

func (description StoreDescription) Validate() error