---
title: internal/plandag
description: Go API reference for the plandag package.
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# plandag

```go
import "github.com/jbcom/radioactive-ralph/internal/plandag"
```

Package plandag owns the SQLite schema, DAG operations, and sync protocol for user\-facing plans.

The schema is embedded under schema/\*.sql and applied in lexical order by Migrate. The schema\_version is tracked in a dedicated table so future versions can detect skew and refuse to open a DB newer than the running binary supports.

## Index

- [Variables](<#variables>)
- [func Migrate\(db \*sql.DB\) error](<#Migrate>)
- [type CreatePlanOpts](<#CreatePlanOpts>)
- [type CreateTaskOpts](<#CreateTaskOpts>)
- [type Options](<#Options>)
- [type Plan](<#Plan>)
- [type PlanStatus](<#PlanStatus>)
- [type SessionMode](<#SessionMode>)
- [type SessionOpts](<#SessionOpts>)
- [type SessionTransport](<#SessionTransport>)
- [type SessionVariantOpts](<#SessionVariantOpts>)
- [type Store](<#Store>)
  - [func Open\(ctx context.Context, opts Options\) \(\*Store, error\)](<#Open>)
  - [func \(s \*Store\) AddDep\(ctx context.Context, planID, taskID, dependsOn string\) error](<#Store.AddDep>)
  - [func \(s \*Store\) AttachPlan\(ctx context.Context, sessionID, planID string\) error](<#Store.AttachPlan>)
  - [func \(s \*Store\) ClaimNextReady\(ctx context.Context, planID, variant, sessionID, sessionVariantID string\) \(\*Task, error\)](<#Store.ClaimNextReady>)
  - [func \(s \*Store\) Close\(\) error](<#Store.Close>)
  - [func \(s \*Store\) CloseSession\(ctx context.Context, sessionID string\) error](<#Store.CloseSession>)
  - [func \(s \*Store\) CreatePlan\(ctx context.Context, o CreatePlanOpts\) \(string, error\)](<#Store.CreatePlan>)
  - [func \(s \*Store\) CreateSession\(ctx context.Context, o SessionOpts\) \(string, error\)](<#Store.CreateSession>)
  - [func \(s \*Store\) CreateSessionVariant\(ctx context.Context, o SessionVariantOpts\) \(string, error\)](<#Store.CreateSessionVariant>)
  - [func \(s \*Store\) CreateTask\(ctx context.Context, o CreateTaskOpts\) error](<#Store.CreateTask>)
  - [func \(s \*Store\) DB\(\) \*sql.DB](<#Store.DB>)
  - [func \(s \*Store\) GetPlan\(ctx context.Context, id string\) \(\*Plan, error\)](<#Store.GetPlan>)
  - [func \(s \*Store\) GetTask\(ctx context.Context, planID, id string\) \(\*Task, error\)](<#Store.GetTask>)
  - [func \(s \*Store\) HeartbeatSession\(ctx context.Context, sessionID string\) error](<#Store.HeartbeatSession>)
  - [func \(s \*Store\) ListPlans\(ctx context.Context, statuses \[\]PlanStatus\) \(\[\]Plan, error\)](<#Store.ListPlans>)
  - [func \(s \*Store\) MarkDone\(ctx context.Context, planID, taskID, sessionID string, evidenceJSON string\) \(\[\]Task, error\)](<#Store.MarkDone>)
  - [func \(s \*Store\) MarkFailed\(ctx context.Context, planID, taskID, sessionID, reason string, maxRetries int\) \(retried bool, err error\)](<#Store.MarkFailed>)
  - [func \(s \*Store\) Ready\(ctx context.Context, planID string\) \(\[\]Task, error\)](<#Store.Ready>)
  - [func \(s \*Store\) SetPlanStatus\(ctx context.Context, id string, status PlanStatus\) error](<#Store.SetPlanStatus>)
- [type Task](<#Task>)
- [type TaskStatus](<#TaskStatus>)


## Variables

<a name="ErrDuplicateSlug"></a>ErrDuplicateSlug is returned when a plan with \(repo\_path, slug\) already exists. Callers either pick a new slug or update.

```go
var ErrDuplicateSlug = errors.New("plandag: plan with slug already exists in this repo")
```

<a name="ErrNoReadyTask"></a>ErrNoReadyTask indicates ClaimNextReady found nothing claimable.

```go
var ErrNoReadyTask = errors.New("plandag: no ready task")
```

<a name="Migrate"></a>
## func [Migrate](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/migrate.go#L30>)

```go
func Migrate(db *sql.DB) error
```

Migrate brings db up to currentSchemaVersion by applying any pending \*.up.sql migrations in lexical order.

Migrations are idempotent per\-version via SQLite's user\_version PRAGMA. Each migration runs inside a transaction.

<a name="CreatePlanOpts"></a>
## type [CreatePlanOpts](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L44-L52>)

CreatePlanOpts configures plan creation. The caller supplies slug \+ title; ID is generated via Store.uuid\(\).

```go
type CreatePlanOpts struct {
    Slug           string
    Title          string
    RepoPath       string
    RepoRemote     string
    PrimaryVariant string
    Confidence     int
    TagsJSON       string
}
```

<a name="CreateTaskOpts"></a>
## type [CreateTaskOpts](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L49-L59>)

CreateTaskOpts configures task creation.

```go
type CreateTaskOpts struct {
    PlanID          string
    ID              string // stable slug (operator-chosen or fixit-emitted)
    Description     string
    Complexity      string
    Effort          string
    VariantHint     string
    ContextBoundary bool
    AcceptanceJSON  string
    ParentTaskID    string
}
```

<a name="Options"></a>
## type [Options](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/store.go#L22-L32>)

Options configures Open.

```go
type Options struct {
    // DSN is a modernc.org/sqlite DSN, e.g.
    // "file:/path/to/plans.db?_pragma=foreign_keys(1)&_pragma=journal_mode(WAL)"
    DSN string

    // Clock is swappable for tests. Nil defaults to clockwork.NewRealClock().
    Clock clockwork.Clock

    // UUID is swappable for tests. Nil defaults to uuid.NewV7().
    UUID func() string
}
```

<a name="Plan"></a>
## type [Plan](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L27-L40>)

Plan is the durable row.

```go
type Plan struct {
    ID             string
    Slug           string
    Title          string
    RepoPath       string
    RepoRemote     string
    Status         PlanStatus
    PrimaryVariant string
    Confidence     int
    CreatedAt      time.Time
    UpdatedAt      time.Time
    LastSessionAt  sql.NullTime
    TagsJSON       string // JSON array
}
```

<a name="PlanStatus"></a>
## type [PlanStatus](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L13>)

PlanStatus enumerates the lifecycle states a plan can be in.

```go
type PlanStatus string
```

<a name="PlanStatusDraft"></a>Plan lifecycle states.

```go
const (
    PlanStatusDraft         PlanStatus = "draft"
    PlanStatusActive        PlanStatus = "active"
    PlanStatusPaused        PlanStatus = "paused"
    PlanStatusDone          PlanStatus = "done"
    PlanStatusFailedPartial PlanStatus = "failed_partial"
    PlanStatusArchived      PlanStatus = "archived"
    PlanStatusAbandoned     PlanStatus = "abandoned"
)
```

<a name="SessionMode"></a>
## type [SessionMode](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L11>)

SessionMode identifies portable\-stdio vs durable\-HTTP modes.

```go
type SessionMode string
```

<a name="SessionModePortable"></a>Session execution modes.

```go
const (
    SessionModePortable SessionMode = "portable"
    SessionModeDurable  SessionMode = "durable"
)
```

<a name="SessionOpts"></a>
## type [SessionOpts](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L30-L37>)

SessionOpts configures CreateSession.

```go
type SessionOpts struct {
    ID           string // optional; caller may pass an existing UUID. Empty → auto.
    Mode         SessionMode
    Transport    SessionTransport
    PID          int
    PIDStartTime string
    Host         string
}
```

<a name="SessionTransport"></a>
## type [SessionTransport](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L20>)

SessionTransport identifies stdio / http / sse transports.

```go
type SessionTransport string
```

<a name="SessionTransportStdio"></a>Session transport types.

```go
const (
    SessionTransportStdio SessionTransport = "stdio"
    SessionTransportHTTP  SessionTransport = "http"
    SessionTransportSSE   SessionTransport = "sse"
)
```

<a name="SessionVariantOpts"></a>
## type [SessionVariantOpts](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L90-L95>)

SessionVariantOpts configures CreateSessionVariant.

```go
type SessionVariantOpts struct {
    SessionID           string
    VariantName         string
    SubprocessPID       int
    SubprocessStartTime string
}
```

<a name="Store"></a>
## type [Store](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/store.go#L15-L19>)

Store is the plandag handle. It wraps a \*sql.DB plus deterministic clock \+ UUID provider \(test\-swappable\).

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

<a name="Open"></a>
### func [Open](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/store.go#L35>)

```go
func Open(ctx context.Context, opts Options) (*Store, error)
```

Open returns a migrated, ready\-to\-use Store.

<a name="Store.AddDep"></a>
### func \(\*Store\) [AddDep](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L91>)

```go
func (s *Store) AddDep(ctx context.Context, planID, taskID, dependsOn string) error
```

AddDep wires task → depends\_on for the same plan. Rejects cycles.

<a name="Store.AttachPlan"></a>
### func \(\*Store\) [AttachPlan](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L120>)

```go
func (s *Store) AttachPlan(ctx context.Context, sessionID, planID string) error
```

AttachPlan records which session is watching which plan. Used by \`ralph status\` to enumerate active supervision.

<a name="Store.ClaimNextReady"></a>
### func \(\*Store\) [ClaimNextReady](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L210-L213>)

```go
func (s *Store) ClaimNextReady(ctx context.Context, planID, variant, sessionID, sessionVariantID string) (*Task, error)
```

ClaimNextReady is the atomic "claim the next ready task for this variant" operation. Returns the claimed task id, or ErrNoReadyTask if none. Uses BEGIN IMMEDIATE \+ UPDATE ... RETURNING so two parallel ralphs never claim the same task.

<a name="Store.Close"></a>
### func \(\*Store\) [Close](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/store.go#L76>)

```go
func (s *Store) Close() error
```

Close releases DB resources.

<a name="Store.CloseSession"></a>
### func \(\*Store\) [CloseSession](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L84>)

```go
func (s *Store) CloseSession(ctx context.Context, sessionID string) error
```

CloseSession removes a session row. FK cascades clear its variants and attach rows.

<a name="Store.CreatePlan"></a>
### func \(\*Store\) [CreatePlan](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L60>)

```go
func (s *Store) CreatePlan(ctx context.Context, o CreatePlanOpts) (string, error)
```

CreatePlan inserts a fresh plan in draft status and returns the newly generated UUID v7 id.

<a name="Store.CreateSession"></a>
### func \(\*Store\) [CreateSession](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L42>)

```go
func (s *Store) CreateSession(ctx context.Context, o SessionOpts) (string, error)
```

CreateSession inserts a session row. Returns the session id. Called by the MCP server on startup; the session's lifetime is the lifetime of one server process.

<a name="Store.CreateSessionVariant"></a>
### func \(\*Store\) [CreateSessionVariant](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L99>)

```go
func (s *Store) CreateSessionVariant(ctx context.Context, o SessionVariantOpts) (string, error)
```

CreateSessionVariant registers a newly\-spawned ralph subprocess against a session. Returns the variant row id.

<a name="Store.CreateTask"></a>
### func \(\*Store\) [CreateTask](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L62>)

```go
func (s *Store) CreateTask(ctx context.Context, o CreateTaskOpts) error
```

CreateTask inserts a pending task. Callers wire dependencies via AddDep.

<a name="Store.DB"></a>
### func \(\*Store\) [DB](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/store.go#L82>)

```go
func (s *Store) DB() *sql.DB
```

DB returns the underlying \*sql.DB for callers that need raw access. Business\-logic callers should use Store's typed methods instead.

<a name="Store.GetPlan"></a>
### func \(\*Store\) [GetPlan](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L88>)

```go
func (s *Store) GetPlan(ctx context.Context, id string) (*Plan, error)
```

GetPlan loads a plan by id.

<a name="Store.GetTask"></a>
### func \(\*Store\) [GetTask](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L284>)

```go
func (s *Store) GetTask(ctx context.Context, planID, id string) (*Task, error)
```

GetTask loads one task by \(plan\_id, id\).

<a name="Store.HeartbeatSession"></a>
### func \(\*Store\) [HeartbeatSession](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/session.go#L75>)

```go
func (s *Store) HeartbeatSession(ctx context.Context, sessionID string) error
```

HeartbeatSession refreshes last\_heartbeat for a session. Called periodically by the server. Reaper uses staleness to detect dead sessions.

<a name="Store.ListPlans"></a>
### func \(\*Store\) [ListPlans](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L126>)

```go
func (s *Store) ListPlans(ctx context.Context, statuses []PlanStatus) ([]Plan, error)
```

ListPlans returns plans matching filter. Empty filter → active \+ paused.

<a name="Store.MarkDone"></a>
### func \(\*Store\) [MarkDone](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L319>)

```go
func (s *Store) MarkDone(ctx context.Context, planID, taskID, sessionID string, evidenceJSON string) ([]Task, error)
```

MarkDone transitions a running task to done, logs the event, and returns the set of newly\-ready downstream tasks.

<a name="Store.MarkFailed"></a>
### func \(\*Store\) [MarkFailed](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L358>)

```go
func (s *Store) MarkFailed(ctx context.Context, planID, taskID, sessionID, reason string, maxRetries int) (retried bool, err error)
```

MarkFailed transitions a running task to failed or retries.

<a name="Store.Ready"></a>
### func \(\*Store\) [Ready](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L158>)

```go
func (s *Store) Ready(ctx context.Context, planID string) ([]Task, error)
```

Ready returns tasks that are ready to run — every dependency is \`done\` \(or \`skipped\`\). Result is ordered by created\_at for stable test output.

<a name="Store.SetPlanStatus"></a>
### func \(\*Store\) [SetPlanStatus](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/plan.go#L113>)

```go
func (s *Store) SetPlanStatus(ctx context.Context, id string, status PlanStatus) error
```

SetPlanStatus updates the plan's status column.

<a name="Task"></a>
## type [Task](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L28-L46>)

Task is a DAG node.

```go
type Task struct {
    ID                 string
    PlanID             string
    Description        string
    Complexity         string
    Effort             string
    VariantHint        string
    ContextBoundary    bool
    AcceptanceJSON     string
    Status             TaskStatus
    AssignedVariant    string
    ClaimedBySession   string
    ClaimedByVariantID string
    RetryCount         int
    ReclaimCount       int
    ParentTaskID       string
    CreatedAt          time.Time
    UpdatedAt          time.Time
}
```

<a name="TaskStatus"></a>
## type [TaskStatus](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/plandag/task.go#L13>)

TaskStatus enumerates valid task lifecycle states.

```go
type TaskStatus string
```

<a name="TaskStatusPending"></a>Task lifecycle states.

```go
const (
    TaskStatusPending              TaskStatus = "pending"
    TaskStatusReady                TaskStatus = "ready"
    TaskStatusReadyPendingApproval TaskStatus = "ready_pending_approval"
    TaskStatusRunning              TaskStatus = "running"
    TaskStatusDone                 TaskStatus = "done"
    TaskStatusFailed               TaskStatus = "failed"
    TaskStatusSkipped              TaskStatus = "skipped"
    TaskStatusDecomposed           TaskStatus = "decomposed"
)
```

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)