beads/issueops/issueops.go
Julian Knutsen ff6eeedbf6
feat(update): enforce close policy when a status update crosses into done (#5206)
A generic status update crossing from a non-done into a done-category status now enforces close
policy — the open-children refusal and the live-direct-blocker refusal — instead of bypassing it.
bd update --force gains a second meaning: it overrides close policy as well as the assignee-transfer fence.

Enforcement lives at the two storage-layer update funnels rather than at call sites, so every status-capable
path is covered by construction. The override travels as a reserved update-map key each funnel pops before
field validation, so a caller that fails to plumb it is refused loudly by name rather than silently losing
the override.

Breaking for scripts relying on bd update -s closed to bypass the checks bd close applies. bd batch gains
'force=true'; an unforced refusal rolls back the batch. Tracker sync-pull always forces. bd batch close is
unchanged.
2026-07-31 18:23:06 -07:00

349 lines
15 KiB
Go

// Package issueops declares the public values used for guarded issue mutations.
package issueops
import (
"context"
"encoding/json"
"time"
"github.com/steveyegge/beads/internal/types"
)
// Issue is the canonical Beads issue model.
type Issue = types.Issue
// Status is an issue lifecycle status.
type Status = types.Status
// IssueType classifies an issue.
type IssueType = types.IssueType
// PersistenceMode selects the complete persistence state for an issue.
type PersistenceMode = types.PersistenceMode
// Status values accepted by issue operations.
const (
StatusOpen = types.StatusOpen
StatusInProgress = types.StatusInProgress
StatusBlocked = types.StatusBlocked
StatusDeferred = types.StatusDeferred
StatusClosed = types.StatusClosed
StatusPinned = types.StatusPinned
StatusHooked = types.StatusHooked
)
// Persistence mode values accepted by issue operations.
const (
PersistenceModePersistent = types.PersistenceModePersistent
PersistenceModeEphemeral = types.PersistenceModeEphemeral
PersistenceModeNoHistory = types.PersistenceModeNoHistory
)
// Waits-for gate values accepted by issue operations.
const (
WaitsForAllChildren = types.WaitsForAllChildren
WaitsForAnyChildren = types.WaitsForAnyChildren
)
// Field distinguishes an omitted value from an explicitly supplied zero value.
type Field[T any] struct {
// Set reports whether Value was supplied.
Set bool
// Value is the supplied value, including a zero or nil value.
Value T
}
// LabelPatch describes ordered label replacement and incremental edits.
// Operations apply Replace, then Add, then Remove, so removal wins when the
// same label appears in more than one edit.
type LabelPatch struct {
// Add contains labels to add after any replacement.
Add []string
// Remove contains labels to remove after replacement and addition.
Remove []string
// Replace supplies the starting complete label set when Set is true.
Replace Field[[]string]
}
// MetadataPatch describes metadata replacement or ordered incremental edits.
// Replace is mutually exclusive with Merge, Set, and Unset. Without Replace,
// operations apply Merge, then Set keys in deterministic order, then Unset, so
// unsetting a key wins over setting or merging that key.
type MetadataPatch struct {
// Replace replaces the complete metadata document when Set is true. A nil or
// empty Value clears metadata; a nonempty Value must be valid JSON.
Replace Field[json.RawMessage]
// Merge merges a metadata document into the current value. A nil or empty
// Value is invalid; a nonempty Value must be a JSON object.
Merge Field[json.RawMessage]
// Set writes individual metadata keys in deterministic key order.
Set map[string]json.RawMessage
// Unset removes individual metadata keys after all other edits.
Unset []string
}
// IssuePatch describes fields that can change on an issue.
type IssuePatch struct {
Title Field[string]
Description Field[string]
Design Field[string]
AcceptanceCriteria Field[string]
// Notes replaces the notes and is mutually exclusive with AppendNotes.
Notes Field[string]
// AppendNotes appends to the notes and is mutually exclusive with Notes.
AppendNotes Field[string]
SpecID Field[string]
AwaitID Field[string]
// Status sets the issue's status. A status that crosses from outside the
// configured done category into it answers to close policy: the update
// refuses with CloseOpenChildrenError or ErrCloseBlocked unless
// UpdateRequest.ForceClosePolicy is set. A done-to-done change and a move
// out of the done category are unaffected. Close and Reopen remain the
// operations that carry the full lifecycle policy — a crossing update
// applies the close policy, not the close semantics.
Status Field[Status]
Priority Field[int]
IssueType Field[IssueType]
Assignee Field[string]
Owner Field[string]
ClosedBySession Field[string]
EstimatedMinutes Field[*int]
ExternalRef Field[*string]
DueAt Field[*time.Time]
DeferUntil Field[*time.Time]
// Persistence selects the complete persistence state. It is unchanged when
// unset; a set value must be a known PersistenceMode. A same current mode is
// a representation-preserving no-op. Every aggregate move is atomic.
// Persistent preserves an existing durable unversioned class; promotion
// from a wisp selects normalized versioned storage. Ephemeral and NoHistory
// select wisp retention modes, never durable unversioned storage. Command
// adapters translate their own flag spelling before constructing this
// request.
Persistence Field[PersistenceMode]
// ParentID is unchanged when unset. A set empty value removes all outgoing
// parent-child edges. A set nonempty value atomically replaces all parents
// with exactly that target and does not inherit labels.
ParentID Field[string]
Labels LabelPatch
Metadata MetadataPatch
}
// CreateDependency describes a dependency created with an issue.
type CreateDependency struct {
TargetID string
Type types.DependencyType
// Reverse writes the dependency from TargetID to the new issue.
Reverse bool
Metadata string
// ThreadID associates this dependency with a discussion thread.
ThreadID string
}
// WaitsFor describes the typed metadata for a DepWaitsFor dependency. It
// records a readiness primitive; it does not define scheduling or execution
// policy.
type WaitsFor struct {
// SpawnerID is required and identifies the dependency target whose children
// are observed.
SpawnerID string
// Gate selects the readiness condition. Empty defaults to
// WaitsForAllChildren; otherwise only the exported waits-for gate constants
// are valid.
Gate string
}
// CreateRequest describes one atomic issue creation.
type CreateRequest struct {
Actor string
// Issue is included in the request's single deep snapshot at method entry;
// every transaction attempt clones that same entry snapshot. Create accepts
// its ID, content, workflow, assignment, timestamps, scheduling,
// external-reference, metadata, wisp, storage-class, marker, gate, source,
// molecule, work-type, and event fields using the canonical create rules. It
// ignores ContentHash, RowVersion, lease state, compaction state, routing
// overrides, hydration flags, and derived fields. Labels are authoritative.
// Issue.Comments and Issue.Dependencies must be empty; supply edges through
// the request's own Dependencies field.
Issue *Issue
// ParentID creates a typed DepParentChild edge. It must not duplicate an
// explicit edge in Dependencies.
ParentID string
// InheritLabelsFromParent copies the parent's labels at creation.
InheritLabelsFromParent bool
// Dependencies is the authoritative set of explicit edges created with the
// issue. Duplicate source-target pairs are rejected. A different type for an
// existing pair is rejected with DependencyTypeConflictError rather than
// silently retyping the edge.
Dependencies []CreateDependency
// WaitsFor creates a typed DepWaitsFor edge. It must not duplicate an
// explicit edge in Dependencies.
WaitsFor *WaitsFor
// ForceIDPrefix permits an explicit ID outside the configured prefix.
ForceIDPrefix bool
}
// UpdateRequest describes an issue update.
type UpdateRequest struct {
Actor, IssueID string
Patch IssuePatch
// Claim atomically claims the issue for Actor. It first sets Assignee to
// Actor and Status to StatusInProgress, then applies Patch; a set
// Patch.Assignee or Patch.Status overrides the corresponding claim value.
// An issue is eligible when its status is built-in StatusOpen or a configured
// active status and it is unassigned, assigned to Actor, or assigned to a
// configured pool. StatusInProgress assigned to the same Actor is an
// idempotent success. A foreign assignment returns ErrAlreadyClaimed; an
// ineligible status returns ErrNotClaimable.
// ExpectedAssignee and ExpectedStatus must be nil when Claim is true because
// the claim has its own compare-and-set eligibility rules.
Claim bool
// ForceAssigneeTransfer bypasses only a genuine transfer away from a foreign
// live in-progress owner. Reasserting the exact current foreign assignee is
// idempotent and needs no force. Assignees configured as claim.pools aliases
// are transferable without force. The zero value enforces the fence. It has
// no effect with Claim or an omitted Patch.Assignee and must be false with
// ExpectedAssignee. It never bypasses other guards — in particular it is
// independent of ForceClosePolicy, and a request that sets it without
// Patch.Assignee is invalid. A command adapter with a single --force flag
// therefore maps that flag to both fields, conditioning this one on an
// assignee edit.
ForceAssigneeTransfer bool
// ForceClosePolicy bypasses only close policy — the open-children refusal
// and the live-direct-blocker refusal — for a Patch.Status that crosses into
// the done category. The zero value enforces the policy. It has no effect
// without such a status change, and never bypasses validation,
// ExpectedVersion, ExpectedAssignee, ExpectedStatus, or the assignee fence.
// It is the update-side spelling of CloseRequest.Force; a command adapter
// that maps one flag to both spells both.
ForceClosePolicy bool
// ExpectedVersion requires the current row version to match before the claim
// and patch. It is an independent precondition and may be combined with Claim.
ExpectedVersion *int64
// ExpectedAssignee requires the current assignee to match. A match authorizes
// the requested Patch.Assignee transfer: this compare-and-set replaces the
// ordinary anti-steal fence. It must be nil with Claim, and
// ForceAssigneeTransfer must be false when it is non-nil.
ExpectedAssignee *string
// ExpectedStatus requires the current status to match. It must be nil when
// Claim is true.
ExpectedStatus *Status
}
// CloseRequest describes an issue closure.
type CloseRequest struct {
Actor string
IssueID string
Reason string
Session string
// Force bypasses only blocker and open-child close policy. It never bypasses
// validation, ExpectedVersion, or lifecycle rules.
Force bool
// ExpectedVersion requires the current row version to match and is checked
// before an idempotent close.
ExpectedVersion *int64
}
// ReopenRequest describes an issue reopening.
type ReopenRequest struct {
Actor string
IssueID string
// Reason records why literal closed and configured done statuses move to
// open. Non-done statuses are unchanged.
Reason string
// ExpectedVersion requires the current row version to match and is checked
// before a non-done no-op.
ExpectedVersion *int64
}
// CreateResult reports the created issue as a detached snapshot with labels,
// dependencies, and persisted comments.
type CreateResult struct {
// Issue is a detached snapshot with labels, dependencies, and persisted
// comments.
Issue *Issue
}
// UpdateResult reports the post-update issue as a detached post-state snapshot
// with labels and dependency records. Comments are omitted.
type UpdateResult struct {
// Issue is a detached post-state snapshot with labels and dependency records.
// Comments are omitted.
Issue *Issue
// Changed reports whether the request persisted a semantic mutation. It is
// false for same-value patches and no-op updates.
Changed bool
}
// CloseResult reports the post-close issue as a detached post-state snapshot
// with labels and dependency records. Comments are omitted.
type CloseResult struct {
// Issue is a detached post-state snapshot with labels and dependency records.
// Comments are omitted.
Issue *Issue
// Changed reports whether closing persisted a semantic mutation. It is false
// for an idempotent re-close.
Changed bool
// OpenChildren is the number of open children observed by a forced close.
// It is reported even for an idempotent re-close.
OpenChildren int
}
// ReopenResult reports the post-reopen issue as a detached post-state snapshot
// with labels and dependency records. Comments are omitted.
type ReopenResult struct {
// Issue is a detached post-state snapshot with labels and dependency records.
// Comments are omitted.
Issue *Issue
// Changed reports whether reopening persisted a semantic mutation. It is
// false when non-done statuses are unchanged.
Changed bool
}
// Lifecycle describes guarded issue mutations. A new capability gets a new
// role interface and its own accessor; never append a method here.
// Deterministic request validation failures match ErrValidation; when a
// more-specific validation sentinel applies, it remains matchable too.
// Implementations never mutate
// caller-owned request values. Callers must not concurrently mutate
// request-owned mutable values until the call returns; snapshotting does not
// make Go data races safe. Implementations snapshot all request inputs once at
// method entry, deep-cloning caller-owned mutable values into that snapshot.
// They deep-clone that snapshot before every transaction attempt, including
// retries, and apply validation, defaulting, and normalization only to
// attempt-local clones. Result values are unspecified when error is non-nil.
// Refusals and deterministic validation failures leave persistent state
// unchanged. Other operational or commit-finalization errors can have an
// indeterminate durable outcome; callers must reread state before retrying.
type Lifecycle interface {
// Create validates and commits the complete request as one atomic mutation.
// It is create-only across issues and wisps: an occupied ID returns
// ErrAlreadyExists and leaves persistent state unchanged. A refusal or
// validation error also leaves no partial persistent state.
Create(context.Context, CreateRequest) (CreateResult, error)
// Update validates guards and commits the complete request as one atomic
// mutation. A Patch.Status that crosses from outside the configured done
// category into it answers to close policy: an unforced crossing with open
// children returns CloseOpenChildrenError and one with a live direct blocker
// returns ErrCloseBlocked, both without mutation. ForceClosePolicy bypasses
// those two refusals and nothing else. A refusal or validation error leaves
// persistent state unchanged.
Update(context.Context, UpdateRequest) (UpdateResult, error)
// Close validates guards and commits the complete request as one atomic
// mutation. It moves the issue to literal StatusClosed, including from a
// configured done status. ExpectedVersion is checked first, including for an
// idempotent close. An unforced close with open children returns
// CloseOpenChildrenError without mutation. Force bypasses blocker and
// open-child policy and reports OpenChildren, including for an idempotent
// re-close. A refusal or validation error leaves persistent state unchanged.
Close(context.Context, CloseRequest) (CloseResult, error)
// Reopen validates guards and commits the complete request as one atomic
// mutation. It moves literal StatusClosed and configured done statuses to
// StatusOpen; non-done statuses unchanged. A refusal or validation error
// leaves persistent state unchanged.
Reopen(context.Context, ReopenRequest) (ReopenResult, error)
}
// ErrFieldTooLong preserves the canonical model sentinel identity for a value
// that exceeds its field's maximum length. The rest of the operation error
// vocabulary is declared in errors.go.
var ErrFieldTooLong = types.ErrFieldTooLong