Documentation
¶
Overview ¶
Package workcontinuity validates and records task checkpoints so work can resume across agents and sessions. Callers own its source and logger; calls run synchronously under the supplied context, with no background workers or service lifecycle. It owns no listener, credentials, or agent execution.
Index ¶
- Constants
- Variables
- func EncodeCheckpoint(checkpoint *workv1.Checkpoint) (string, error)
- func Fingerprint(issue *workv1.SourceIssue) string
- func RenderTicket(spec *workv1.TicketSpec) (string, error)
- func Resume(snapshot *workv1.SourceSnapshot, revision string, now time.Time, ...) *workv1.ResumeRecord
- func TicketTemplate() *workv1.TicketSpec
- func ValidateCheckpoint(checkpoint *workv1.Checkpoint) error
- func ValidateTaskURL(taskURL string) error
- type Command
- type Continuity
- type GitHubSource
- func (source *GitHubSource) Append(ctx context.Context, taskURL, body string) (*workv1.SourceComment, error)
- func (source *GitHubSource) CreateTicket(ctx context.Context, spec *workv1.TicketSpec) (*workv1.TicketReceipt, error)
- func (source *GitHubSource) Load(ctx context.Context, taskURL string) (*workv1.SourceSnapshot, error)
- type HTTPGitHubSource
- type ISource
- type Option
Constants ¶
const ( CheckpointMarker = "<!-- candace-work-checkpoint:v1 -->" SchemaVersion uint32 = 1 DefaultMaxAge = 24 * time.Hour IssueOpen = "open" IssueClosed = "closed" )
Variables ¶
Functions ¶
func EncodeCheckpoint ¶
func EncodeCheckpoint(checkpoint *workv1.Checkpoint) (string, error)
EncodeCheckpoint produces the one marked comment format consumed on resume.
func Fingerprint ¶
func Fingerprint(issue *workv1.SourceIssue) string
Fingerprint excludes updated_at: posting a checkpoint itself updates an issue.
func RenderTicket ¶
func RenderTicket(spec *workv1.TicketSpec) (string, error)
RenderTicket validates author input and applies the repository's ticket template. The template renders only the development paths selected by the typed input.
func Resume ¶
func Resume(snapshot *workv1.SourceSnapshot, revision string, now time.Time, maxAge time.Duration) *workv1.ResumeRecord
Resume evaluates a source snapshot without executing any saved instructions. READY means current handoff data, not authorization or a live-worker claim.
func TicketTemplate ¶
func TicketTemplate() *workv1.TicketSpec
TicketTemplate supplies editable input for the same contract creation uses.
func ValidateCheckpoint ¶
func ValidateCheckpoint(checkpoint *workv1.Checkpoint) error
ValidateCheckpoint combines generated field invariants with lifecycle rules.
func ValidateTaskURL ¶
ValidateTaskURL accepts exactly the issue identities the continuity source can read and append to; consumers use it before retaining an association.
Types ¶
type Continuity ¶
type Continuity struct {
// contains filtered or unexported fields
}
Continuity validates and records handoffs against an authoritative issue source.
func NewContinuity ¶
func NewContinuity(options ...Option) (*Continuity, error)
NewContinuity validates the source, trace sink and freshness policy before use.
func (*Continuity) Checkpoint ¶
func (service *Continuity) Checkpoint(ctx context.Context, taskURL string, input *workv1.Checkpoint) (*workv1.ResumeRecord, error)
Checkpoint appends a validated receipt, verifies it by rereading the source, and rejects concurrent forks. It does not claim a GitHub transaction or lease.
func (*Continuity) Resume ¶
func (service *Continuity) Resume(ctx context.Context, taskURL, revision string) (*workv1.ResumeRecord, error)
type GitHubSource ¶
type GitHubSource struct {
// contains filtered or unexported fields
}
GitHubSource uses the operator's existing gh authentication. The application does not read, copy, print or persist the credential itself.
func NewGitHubSource ¶
func NewGitHubSource(command Command) *GitHubSource
func (*GitHubSource) Append ¶
func (source *GitHubSource) Append(ctx context.Context, taskURL, body string) (*workv1.SourceComment, error)
func (*GitHubSource) CreateTicket ¶
func (source *GitHubSource) CreateTicket(ctx context.Context, spec *workv1.TicketSpec) (*workv1.TicketReceipt, error)
CreateTicket validates and resolves dependencies before creating an issue, then attaches GitHub's native blocked-by relationships for strict prerequisites. Stackable dependencies remain linked in the body without a native blocker. GitHub offers no transaction across these operations; a partial receipt retains the issue URL. Conditions describe the requested outcome; this method does not schedule work or decide whether a dependency has been satisfied.
func (*GitHubSource) Load ¶
func (source *GitHubSource) Load(ctx context.Context, taskURL string) (*workv1.SourceSnapshot, error)
type HTTPGitHubSource ¶
type HTTPGitHubSource struct {
// contains filtered or unexported fields
}
HTTPGitHubSource performs continuity I/O through the caller's authenticated client in the existing process. The host owns credentials and client lifetime. Load reads at most 100 comment pages and 16 MiB of response bodies in total; exceeding either bound fails rather than returning an incomplete history.
func NewHTTPGitHubSource ¶
func NewHTTPGitHubSource(client *http.Client) (*HTTPGitHubSource, error)
func (*HTTPGitHubSource) Append ¶
func (source *HTTPGitHubSource) Append(ctx context.Context, taskURL, body string) (*workv1.SourceComment, error)
Append validates the returned identity and body but never retries a write. An error can follow a committed write; inspect the issue before retrying. The continuity service separately reloads history to verify its checkpoint chain.
func (*HTTPGitHubSource) Load ¶
func (source *HTTPGitHubSource) Load(ctx context.Context, taskURL string) (*workv1.SourceSnapshot, error)
type ISource ¶
type ISource interface {
Load(ctx context.Context, taskURL string) (*workv1.SourceSnapshot, error)
Append(ctx context.Context, taskURL, body string) (*workv1.SourceComment, error)
}
ISource is the issue authority used to read and append task checkpoints.
type Option ¶
type Option func(service *Continuity)
func WithLogger ¶
func WithLogger(logger *telemetry.JSONLLogger) Option
Source Files