sharedtask

package
v0.37.0 Latest Latest
Warning

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

 Go to latest Published: Jul 3, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

View Source 
const (
	SchemaTaskJournal = "fak.shared-task-journal.v1"
	SchemaJournal     = SchemaTaskJournal
)
View Source 
const (
	SchemaTask        = "fak.shared-task.v1"
	SchemaEvent       = "fak.shared-event.v1"
	SchemaPatch       = "fak.shared-patch.v1"
	SchemaPatchResult = "fak.shared-patch-result.v1"
)
View Source 
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"
)
View Source 
const SchemaArtifactRef = "fak.shared-artifact-ref.v1"

SchemaArtifactRef is the envelope schema name for a standalone disaggregated artifact reference — the sixth contract schema; the other five are declared in sharedtask.go and journal.go.

Variables

This section is empty.

Functions

func ComputeRev 

func ComputeRev(record TaskRecord) string

func ContractJSONFiles added in v0.37.0 

func ContractJSONFiles(path string) ([]string, error)

ContractJSONFiles lists the JSON files to validate: the path itself when it is a file, else every *.json under the directory in stable sorted order.

func EventRef 

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

func EventTopic 

func EventTopic(taskID string) a2achan.ChannelKey

func FormatContractCounts added in v0.37.0 

func FormatContractCounts(counts map[string]int) string

FormatContractCounts renders per-schema counts as the stable "name=n, ..." summary line the contract recipes print.

func LoadContractSchema added in v0.37.0 

func LoadContractSchema(schemaDir, name string) (map[string]any, error)

LoadContractSchema reads and parses the named contract schema from schemaDir.

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

func ValidateContractDoc added in v0.37.0 

func ValidateContractDoc(schemaDir, docPath string) (map[string]int, error)

ValidateContractDoc validates every ```json``` example block in the contract doc and returns per-schema counts, so the prose examples can never drift from the schemas they illustrate.

func ValidateContractFiles added in v0.37.0 

func ValidateContractFiles(schemaDir string, paths []string) (map[string]int, error)

ValidateContractFiles envelope-validates each file and returns per-schema counts.

func ValidateContractSequence added in v0.37.0 

func ValidateContractSequence(schemaDir, path string) (map[string]int, error)

ValidateContractSequence checks the full collaborative-sequence fixture shape: a task record, at least one materialized journal bound to the same task with accepted-event snapshots, at least one accepted patch result, and a title replacement patch (the canonical co-edit the example narrates).

func ValidateContractVerdicts added in v0.37.0 

func ValidateContractVerdicts(schemaDir, path string) (map[string]int, error)

ValidateContractVerdicts checks the non-acceptance fixture shape: every non-accepted verdict a UI must render (needs_approval, denied, quarantined) is present, each carries a reason, and none advances the task revision.

func ValidateEnvelope added in v0.37.0 

func ValidateEnvelope(envelope map[string]any, schemaDir string) (string, error)

ValidateEnvelope validates one decoded record against the schema named by its own "schema" field and returns that schema name.

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
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.