sharedtask

Documentation

Overview

Package sharedtask is the in-memory reference fold for collaborative task records. It is deliberately off the hot path: adapters can reuse its patch, conflict, scope, event, and journal semantics without each inventing a separate task-state contract.

Index

• Constants
• func ComputeRev(record TaskRecord) string
• func EventRef(event Event) (abi.Ref, error)
• func EventTopic(taskID string) a2achan.ChannelKey
• func PublishEvent(ctx context.Context, bus *a2achan.Bus, from string, event Event, ...) (abi.Verdict, int, error)
• func PublishEventScoped(ctx context.Context, bus *a2achan.Bus, from string, event Event, ...) (abi.Verdict, int, error)
• func ScopedEventTopic(taskID string, maxScope Scope) a2achan.ChannelKey
• type Actor
• type Approval
• type ArtifactRef
• type BodyRef
• type Conflict
• type Decision
• type Denial
• type Durability
• type Event
• type EventLogView
• type Journal
  • func (j Journal) ComputeDigest() string
  • func (j Journal) CurrentRecord() (TaskRecord, bool)
  • func (j Journal) Verify() error
• type JournalEntry
• type Note
• type Op
• type Patch
• type PatchResult
• type Policy
• type Quarantine
• type Scope
• type Store
  • func LoadJournal(j Journal, policy Policy) (*Store, error)
  • func NewStore(policy Policy) *Store
  • func (s *Store) Apply(patch Patch) PatchResult
  • func (s *Store) ApplyAndPublish(ctx context.Context, bus *a2achan.Bus, from string, patch Patch, ...) (PatchResult, abi.Verdict, int, error)
  • func (s *Store) ApplyAndPublishScoped(ctx context.Context, bus *a2achan.Bus, from string, patch Patch, ...) (PatchResult, abi.Verdict, int, error)
  • func (s *Store) Create(record TaskRecord) (TaskRecord, error)
  • func (s *Store) Event(taskID, eventID string) (Event, bool)
  • func (s *Store) Events(taskID string) []Event
  • func (s *Store) EventsView(taskID string, policy ViewPolicy) (EventLogView, bool)
  • func (s *Store) Get(taskID string) (TaskRecord, bool)
  • func (s *Store) Journal(taskID string) (Journal, bool)
  • func (s *Store) SubscribeScopedView(bus *a2achan.Bus, taskID string, policy ViewPolicy) (TaskSubscription, bool)
  • func (s *Store) SubscribeView(bus *a2achan.Bus, taskID string, policy ViewPolicy) (TaskSubscription, bool)
  • func (s *Store) View(taskID string, policy ViewPolicy) (TaskView, bool)
• type Taint
• type TaskRecord
• type TaskSubscription
• type TaskView
• type Verdict
• type ViewPolicy

Constants

const (
	SchemaTaskJournal = "fak.shared-task-journal.v1"
	SchemaJournal     = SchemaTaskJournal
)

const (
	SchemaTask        = "fak.shared-task.v1"
	SchemaEvent       = "fak.shared-event.v1"
	SchemaPatch       = "fak.shared-patch.v1"
	SchemaPatchResult = "fak.shared-patch-result.v1"
)

const (
	ReasonApprovalRequired   = "APPROVAL_REQUIRED"
	ReasonArtifactQuarantine = "ARTIFACT_QUARANTINED"
	ReasonArtifactWitness    = "ARTIFACT_WITNESS_MISSING"
	ReasonBodyQuarantine     = "BODY_QUARANTINED"
	ReasonBodyWitness        = "BODY_WITNESS_MISSING"
	ReasonMissingDecision    = "MISSING_DECISION"
	ReasonScopeDenied        = "SCOPE_WIDEN_FORBIDDEN"
	ReasonStaleBase          = "STALE_BASE"
	ReasonUnsupportedPatch   = "UNSUPPORTED_PATCH"
)

Functions

func ComputeRev

func ComputeRev(record TaskRecord) string

func EventRef

func EventRef(event Event) (abi.Ref, error)

func EventTopic

func EventTopic(taskID string) a2achan.ChannelKey

func PublishEvent

func PublishEvent(ctx context.Context, bus *a2achan.Bus, from string, event Event, caps ...abi.Capability) (abi.Verdict, int, error)

func PublishEventScoped

func PublishEventScoped(ctx context.Context, bus *a2achan.Bus, from string, event Event, caps ...abi.Capability) (abi.Verdict, int, error)

func ScopedEventTopic

func ScopedEventTopic(taskID string, maxScope Scope) a2achan.ChannelKey

Types

type Actor

type Actor struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
}

type Approval

type Approval struct {
	DecisionID string `json:"decision_id"`
	State      string `json:"state"`
	Reason     string `json:"reason"`
}

type ArtifactRef

type ArtifactRef struct {
	ArtifactID          string `json:"artifact_id"`
	Ref                 string `json:"ref"`
	MediaType           string `json:"media_type"`
	Taint               Taint  `json:"taint"`
	Scope               Scope  `json:"scope"`
	Store               string `json:"store"`
	DeletionCertificate string `json:"deletion_certificate,omitempty"`
}

type BodyRef

type BodyRef struct {
	Kind                string     `json:"kind"`
	Digest              string     `json:"digest"`
	Bytes               int64      `json:"bytes"`
	Taint               Taint      `json:"taint"`
	Scope               Scope      `json:"scope"`
	Durability          Durability `json:"durability"`
	Store               string     `json:"store,omitempty"`
	DeletionCertificate string     `json:"deletion_certificate,omitempty"`
}

type Conflict

type Conflict struct {
	Path          string `json:"path"`
	BaseValue     any    `json:"base_value"`
	CurrentValue  any    `json:"current_value"`
	ProposedValue any    `json:"proposed_value"`
	Resolution    string `json:"resolution"`
}

type Decision

type Decision struct {
	DecisionID string `json:"decision_id"`
	State      string `json:"state"`
	Reason     string `json:"reason"`
}

type Denial

type Denial struct {
	Policy        string `json:"policy"`
	Actor         Actor  `json:"actor"`
	RequiredScope Scope  `json:"required_scope"`
}

type Durability

type Durability string

const (
	DurabilityTurn    Durability = "turn"
	DurabilitySession Durability = "session"
	DurabilityBounded Durability = "bounded"
	DurabilityDurable Durability = "durable"
)

type Event

type Event struct {
	Schema      string     `json:"schema"`
	EventID     string     `json:"event_id"`
	TaskID      string     `json:"task_id"`
	PrevEvent   string     `json:"prev_event"`
	EventKind   string     `json:"event_kind"`
	Actor       Actor      `json:"actor"`
	BaseRev     string     `json:"base_rev"`
	NextRev     string     `json:"next_rev"`
	Scope       Scope      `json:"scope"`
	Durability  Durability `json:"durability"`
	Taint       Taint      `json:"taint"`
	PatchDigest string     `json:"patch_digest"`
	Verdict     Verdict    `json:"verdict"`
	Reason      string     `json:"reason"`
	TS          string     `json:"ts"`
}

type EventLogView

type EventLogView struct {
	Events         []Event
	RedactedEvents int
}

type Journal

type Journal struct {
	Schema  string         `json:"schema"`
	TaskID  string         `json:"task_id"`
	Initial TaskRecord     `json:"initial"`
	Entries []JournalEntry `json:"entries"`
	Digest  string         `json:"digest"`
}

func (Journal) ComputeDigest

func (j Journal) ComputeDigest() string

func (Journal) CurrentRecord

func (j Journal) CurrentRecord() (TaskRecord, bool)

func (Journal) Verify

func (j Journal) Verify() error

type JournalEntry

type JournalEntry struct {
	Event        Event      `json:"event"`
	Record       TaskRecord `json:"record"`
	RecordDigest string     `json:"record_digest"`
}

type Note

type Note struct {
	NoteID    string  `json:"note_id"`
	Kind      string  `json:"kind"`
	BodyRef   BodyRef `json:"body_ref"`
	Author    Actor   `json:"author"`
	CreatedAt string  `json:"created_at"`
}

type Op

type Op struct {
	Op    string `json:"op"`
	Path  string `json:"path"`
	Value any    `json:"value,omitempty"`
}

type Patch

type Patch struct {
	Schema     string     `json:"schema"`
	TaskID     string     `json:"task_id"`
	BaseRev    string     `json:"base_rev"`
	Actor      Actor      `json:"actor"`
	Scope      Scope      `json:"scope"`
	Durability Durability `json:"durability"`
	Ops        []Op       `json:"ops"`
	Message    string     `json:"message"`
}

type PatchResult

type PatchResult struct {
	Schema     string      `json:"schema"`
	TaskID     string      `json:"task_id"`
	BaseRev    string      `json:"base_rev"`
	CurrentRev string      `json:"current_rev"`
	Verdict    Verdict     `json:"verdict"`
	Reason     string      `json:"reason"`
	EventID    string      `json:"event_id,omitempty"`
	RecordRef  string      `json:"record_ref,omitempty"`
	Approval   *Approval   `json:"approval,omitempty"`
	Denial     *Denial     `json:"denial,omitempty"`
	Quarantine *Quarantine `json:"quarantine,omitempty"`
	Conflict   *Conflict   `json:"conflict,omitempty"`
}

type Policy

type Policy struct {
	MaxScope           Scope
	RequireApproval    bool
	ApprovalDecisionID string
	ApprovalReason     string
	DenialPolicy       string
	QuarantineSummary  string
}

type Quarantine

type Quarantine struct {
	QuarantineID string `json:"quarantine_id"`
	ArtifactID   string `json:"artifact_id"`
	SubjectKind  string `json:"subject_kind,omitempty"`
	SubjectID    string `json:"subject_id,omitempty"`
	SafeSummary  string `json:"safe_summary"`
}

type Scope

type Scope string

const (
	ScopeAgent  Scope = "agent"
	ScopeFleet  Scope = "fleet"
	ScopeTenant Scope = "tenant"
	ScopePublic Scope = "public"
)

type Store

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

func LoadJournal

func LoadJournal(j Journal, policy Policy) (*Store, error)

func NewStore

func NewStore(policy Policy) *Store

func (*Store) Apply

func (s *Store) Apply(patch Patch) PatchResult

func (*Store) ApplyAndPublish

func (s *Store) ApplyAndPublish(ctx context.Context, bus *a2achan.Bus, from string, patch Patch, caps ...abi.Capability) (PatchResult, abi.Verdict, int, error)

func (*Store) ApplyAndPublishScoped

func (s *Store) ApplyAndPublishScoped(ctx context.Context, bus *a2achan.Bus, from string, patch Patch, caps ...abi.Capability) (PatchResult, abi.Verdict, int, error)

func (*Store) Create

func (s *Store) Create(record TaskRecord) (TaskRecord, error)

func (*Store) Event

func (s *Store) Event(taskID, eventID string) (Event, bool)

func (*Store) Events

func (s *Store) Events(taskID string) []Event

func (*Store) EventsView

func (s *Store) EventsView(taskID string, policy ViewPolicy) (EventLogView, bool)

func (*Store) Get

func (s *Store) Get(taskID string) (TaskRecord, bool)

func (*Store) Journal

func (s *Store) Journal(taskID string) (Journal, bool)

func (*Store) SubscribeScopedView

func (s *Store) SubscribeScopedView(bus *a2achan.Bus, taskID string, policy ViewPolicy) (TaskSubscription, bool)

func (*Store) SubscribeView

func (s *Store) SubscribeView(bus *a2achan.Bus, taskID string, policy ViewPolicy) (TaskSubscription, bool)

func (*Store) View

func (s *Store) View(taskID string, policy ViewPolicy) (TaskView, bool)

type Taint

type Taint string

const (
	TaintTrusted     Taint = "trusted"
	TaintTainted     Taint = "tainted"
	TaintQuarantined Taint = "quarantined"
)

type TaskRecord

type TaskRecord struct {
	Schema        string        `json:"schema"`
	TaskID        string        `json:"task_id"`
	Rev           string        `json:"rev"`
	State         string        `json:"state"`
	Title         string        `json:"title"`
	BodyRef       BodyRef       `json:"body_ref"`
	Artifacts     []ArtifactRef `json:"artifacts"`
	Notes         []Note        `json:"notes"`
	OpenDecisions []Decision    `json:"open_decisions"`
	UpdatedBy     Actor         `json:"updated_by"`
	UpdatedAt     string        `json:"updated_at"`
}

type TaskSubscription

type TaskSubscription struct {
	Topic  a2achan.ChannelKey
	Inbox  a2achan.ChannelKey
	View   TaskView
	Cancel func()
}

type TaskView

type TaskView struct {
	Record            TaskRecord
	BodyVisible       bool
	RedactedArtifacts int
	RedactedNotes     int
}

type Verdict

type Verdict string

const (
	VerdictAccepted      Verdict = "accepted"
	VerdictConflict      Verdict = "conflict"
	VerdictQuarantined   Verdict = "quarantined"
	VerdictDenied        Verdict = "denied"
	VerdictNeedsApproval Verdict = "needs_approval"
)

type ViewPolicy

type ViewPolicy struct {
	MaxScope           Scope
	IncludeQuarantined bool
}