mutation

type Actor ¶

type Actor struct {
	ID   string
	Role string
}

Actor is the envelope's untrusted actor claim. It is compared against the trusted Binding of the Context and never used on its own.

type Binding ¶

type Binding struct {
	ID   string
	Role string
}

Binding is the trusted invocation actor: the role and id of the principal that invoked the tool, as established by the caller's authority layer. It is deliberately a separate type from Actor so that it can never be filled from an envelope by accident. An empty Binding is not "anonymous" and not "OWNER"; it fails closed with UNAUTHORIZED.

Limit: this package validates the binding it is handed (well-formed label, known role, equal to the envelope claim). It cannot authenticate the process that handed it over, and it cannot tell two processes under the same UID apart. Deciding who may furnish which binding is the runtime enforcement profile's job (qualification work), not this library's.

type CompleteManualPayload ¶

type CompleteManualPayload struct {
	Reason   string
	Evidence []wire.Digest
}

CompleteManualPayload is {reason, evidence}.

type Context ¶

type Context struct {
	// Binding is the trusted actor (see Binding). Required.
	Binding Binding
	// Queue is the current queue manifest (canonical record). Required.
	Queue *intent.Queue
	// Policy is the current policy (roles row removal, gate ids). Required.
	Policy *intent.Policy
	// Inventory holds every current ticket record of the queue, including
	// tombstones, so that ID membership, dependency existence and cycles
	// are checked against the full set (TM-V0-005). Required.
	Inventory *ticket.Inventory
	// Attempts answers attempt liveness (§3.2). A nil oracle or a
	// NOT_OBSERVED answer is treated as "possibly live": an acceptance-
	// relevant mutation is then refused BLOCKED/ATTEMPT_LIVE (fail closed).
	Attempts ticket.AttemptOracle
	// Requests is the request-ID index consulted for TM-V0-006 replay.
	// Required: a nil index is refused VALIDATION_FAILED/MALFORMED before any
	// computation, never treated as "no prior request" (a Context built
	// without its index would otherwise commit every retry twice).
	Requests RequestIndex
	// Now is the logical timestamp recorded as updatedAt, createdAt,
	// placedAt, grantedAt and recordedAt. Advisory only (§2).
	Now wire.Timestamp
}

Context carries every fact a mutation depends on. All of it is explicit input; nothing is read from disk, a clock or the environment.

type CreatePayload ¶

type CreatePayload struct {
	LocalToken         *string
	Title              string
	Body               *string
	Kind               string
	Owner              *string
	Milestone          *string
	Priority           string
	Order              wire.Count
	Labels             []string
	Dependencies       []ticket.Dependency
	AcceptanceCriteria []string
	RequirementRefs    []string
	Source             ticket.Source
	Effects            ticket.Effects
	Capabilities       []string
	RequiredGates      []string
	ExecutionClass     string
	DueDate            *string
	EstimateMinutes    *wire.Count
	Supersedes         *wire.TicketID
	SupersededBy       *wire.TicketID
}

CreatePayload is the CREATE payload: the full record minus the fields the tool derives (ticketId, revision, acceptanceRevision, previousRecordSha256, status, archivedFrom, completion, holds, approvals, createdAt, updatedAt, updatedBy, shadowOverlay), plus an optional localToken.

type Envelope ¶

type Envelope struct {
	RequestID        string
	Actor            Actor
	QueueID          wire.QueueID
	TargetID         *wire.TicketID // nil only for CREATE
	ExpectedRevision *wire.Count    // nil only for CREATE
	Operation        string
	Payload          Payload
	IssuedAt         wire.Timestamp
	// Raw is the exact envelope bytes as decoded (canonical body plus LF).
	// The TM-V0-006 request digest is the SHA-256 of these bytes.
	Raw []byte
}

Envelope is a decoded taskman-mutation/0.

func Decode(data []byte) (*Envelope, error)

func (e *Envelope) Sha256() wire.Digest

func (e *Envelope) Value() wire.Value

type GrantApprovalPayload ¶

type GrantApprovalPayload struct {
	GrantID        string
	Actor          string
	Operation      string
	TargetRevision wire.Count
	Scope          []string
}

GrantApprovalPayload is a grant minus revoked and grantedAt. The grant's actor must equal the trusted Binding id.

type HoldPayload ¶

type HoldPayload struct {
	HoldID string
	Reason string
}

HoldPayload is {holdId, reason}. The hold's actor and placedAt are never taken from the payload: they come from the trusted Binding and the logical timestamp of the Context.

type IndexEntry ¶

type IndexEntry struct {
	RequestID      string
	MutationSha256 wire.Digest
	Outcome        Outcome
}

IndexEntry is one recorded request: the request ID, the SHA-256 of the canonical mutation bytes and the outcome recorded with it (TM-V0-006).

type MemoryIndex ¶

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

MemoryIndex is the explicit in-memory fake used by TCP-01 tests to exercise the TM-V0-006 replay and conflict rules (AS-03). It is never durable, never shared and never evidence of a commit: a test that records an entry here is simulating the transaction the journal would perform, nothing more.

func NewMemoryIndex() *MemoryIndex

func (m *MemoryIndex) Len() int

func (m *MemoryIndex) Lookup(requestID string) (IndexEntry, bool, error)

func (m *MemoryIndex) Record(e IndexEntry) error

type Outcome ¶

type Outcome struct {
	RequestID                   string
	Outcome                     string
	Replayed                    bool
	ResultingRevision           *wire.Count
	ResultingAcceptanceRevision *wire.Count
	ReleaseID                   *string
	ResultingReleaseRevision    *wire.Count
	ReceiptSeq                  *wire.Size
	Codes                       []string
}

Outcome is a taskman-outcome/0 document. ReceiptSeq is nil for every outcome this package produces: a planned result has no receipt. Only the journal commit of TCP-02b fills it, and a Replayed outcome carries whatever the recorded original carried.

func DecodeOutcome(data []byte) (*Outcome, error)

func (o *Outcome) Encode() ([]byte, error)

func (o *Outcome) HasCode(code string) bool

func (o *Outcome) Value() wire.Value

type Payload ¶

type Payload interface {
	// contains filtered or unexported methods
}

Payload is one operation's closed payload (§3.3 table).

type Plan ¶

type Plan struct {
	Outcome        Outcome
	MutationSha256 wire.Digest // SHA-256 of the canonical mutation bytes (TM-V0-006)
	Detail         string      // human explanation of a refusal; never queue prose
	Pre            *ticket.Record
	Post           *ticket.Record // non-nil iff Outcome is a fresh COMPLETED
	QueuePost      *intent.Queue  // non-nil iff CREATE allocated a serial
	Composed       []string       // ADOPT_FILE: the composed operations in order
}

Plan is the pure result of validating and computing one mutation. It is explicitly uncommitted: Outcome.ReceiptSeq is nil, no file changed, no receipt exists, and the request index was only read. A Plan with outcome COMPLETED says what the post record would be; the transaction writer of TCP-02b decides whether it becomes real.

func Adopt(ctx Context, requestID string, canonical *ticket.Record, file []byte) *Plan

func Apply(ctx Context, env *Envelope) *Plan

func (p *Plan) Planned() bool

type PrioritizePayload ¶

type PrioritizePayload struct {
	Priority string
	Order    wire.Count
}

PrioritizePayload is {priority, order}.

type ReasonPayload ¶

type ReasonPayload struct {
	Op     string
	Reason string
}

ReasonPayload is {reason} for REOPEN, ARCHIVE and RESTORE.

type RefinePayload ¶

type RefinePayload struct {
	Present            map[string]bool
	Title              string
	Body               *string
	Kind               string
	Owner              *string
	Milestone          *string
	Labels             []string
	AcceptanceCriteria []string
	RequirementRefs    []string
	DueDate            *string
	EstimateMinutes    *wire.Count
	Supersedes         *wire.TicketID
}

RefinePayload is a non-empty subset of RefineFields. Present names the keys carried; a typed field is meaningful only when its key is present.

func (p *RefinePayload) Has(key string) bool

func (p *RefinePayload) Keys() []string

type ReleaseHoldPayload ¶

type ReleaseHoldPayload struct {
	HoldID string
}

ReleaseHoldPayload is {holdId}.

type RequestIndex ¶

type RequestIndex interface {
	Lookup(requestID string) (IndexEntry, bool, error)
}

RequestIndex answers whether a request ID has already been recorded. The durable implementation is the journal's requests/ index (TCP-02); this package only consults whatever it is given. Only false,nil proves absence; a lookup error refuses before a fresh plan is computed.

type RevokeApprovalPayload ¶

type RevokeApprovalPayload struct {
	GrantID string
	Reason  string
}

RevokeApprovalPayload is {grantId, reason}.

type SetDependenciesPayload ¶

type SetDependenciesPayload struct {
	Dependencies []ticket.Dependency
}

SetDependenciesPayload is the full replacement of dependencies.

type SetEffectsPayload ¶

type SetEffectsPayload struct {
	Effects        ticket.Effects
	Capabilities   []string
	ExecutionClass string
}

SetEffectsPayload is the full replacement of effects, capabilities and executionClass.

type SetGatesPayload ¶

type SetGatesPayload struct {
	RequiredGates []string
}

SetGatesPayload is the full replacement of requiredGates.