beads/issueops/issueops.go
Julian Knutsen a2d43e6792
fix(mol): molecule reads, auto-close and close --continue over http through issueops entries (S16) (#7513)
* fix(create): let a remote backend mint the --parent child id

`bd create --parent` always called the raw GetNextChildID first, which the
http backend does not serve, so every child create on a remote workspace
refused before writing anything. The Lifecycle role already mints
<parent>.<n> for a create that carries a ParentID and no id of its own, on
every backend and inside the create's own transaction; conformance
RunIssueOperationsCreateUnderAParentMintsTheNextChildID pins it on every leg,
the served one included (and the bd-enterprise postgres leg the MC server
runs). So the create route needs no new capability token: on a registered
Remote backend the client skips the raw reservation and lets the server mint.
The local route keeps its reservation so its Dolt commit staging is
unchanged, and an explicit --id beside --parent is still refused up front.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mol): molecule reads, auto-close and close --continue over issueops roles

Over the http backend three molecule paths failed, and two of them
silently:

- `bd mol current` / `bd mol progress` without an id answered "no molecules"
  because the in_progress listing (a raw SearchIssues shape) and the parent
  walk (raw GetDependencyRecordsForIssues) were refused and the refusal was
  swallowed; with an id they refused on raw GetMoleculeProgress.
- The molecule auto-close after `bd close` never ran: findParentMolecules
  swallowed the same refused edge read into "not part of a molecule".
- `bd close --continue` claimed the next step in a raw RunInTransaction.

The direct route now reads molecules through roleMolStore, which answers
through roles every backend serves: EdgeReader (batched at the wire's 100
anchors) for the parent walk, BatchGetter for the roots (Get per id where a
server does not publish issues.batchGet), Relations for the step rows (full
rows; the raw dependents read over http is getIssue's shallow projection,
which zeroed step assignees) and the progress counts, and Reader.List for the
in_progress/hooked listings. The auto-close closes the root through
Lifecycle.Close, and the --continue claim is one Lifecycle.Update guarded by
ExpectedStatus=open.

No refusal is swallowed any more: findParentMolecules, the molecule finders
and the hooked scan return their errors; `mol current/progress` report them;
the auto-close stays best effort but warns on stderr; AdvanceToNextStep only
moves on to the next ready step when the claim LOST a race (status mismatch,
not claimable, already claimed) and returns anything else. The one heuristic
still skipped is the id-pattern heal in loadDescendants, and only for an
ErrUnsupported backend that cannot express an id-prefix search; other
failures now surface. `mol current`/`mol progress` leave the
types.IssueFilter forbidigo hole, since they no longer build a filter.

gc does not depend on bd's molecule auto-close: it runs its own
(cmd/gc/molecule_autoclose.go, from the bd on_close hook and the
controller's bead-close events). Its worker prompts do run `bd mol current`.

Served e2e (TestE2E_MoleculesOverHTTP): create --parent mints <root>.1/.2,
mol current <id> is non-empty with the full in-progress step, mol progress
counts, close --continue auto-advances, closing the last step auto-closes
the root. `mol current` without an id now refuses out loud on this stack
(asserted: never an empty list); its non-empty assertion is skipped until
S6c (externaldeps reader passthrough) is underneath.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mol): list molecule candidates with the four wire knobs, drop the S6c skip

On top of S6c the in_progress listing behind 'bd mol current' (no id)
reaches the v0 wire encoder, which refuses ListRequest.IncludeAllTypes.
Ask for templates, gates, infra and ephemeral rows explicitly, which the
wire publishes, and run the 'mol current without an id' served case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(issueops): one library entry each for molecule auto-close, advance and reads

The molecule rules lived only in cmd/bd, in copies that disagreed: two
auto-close implementations that closed the root through different
library entries outside the step close's transaction, a `close
--continue` claim that set no assignee and could take a step another
agent held on the direct and http routes, and three progress counts.
Every molecule rule now has one implementation in the public issueops
package, composed over three roles every backend serves (BatchGetter,
Relations, EdgeReader): MoleculeRoots, LoadMolecule, AnalyzeMolecule,
ViewMolecule, ReadMoleculeProgress, ActiveMoleculeIDs,
CompletedMolecule. Membership is the parent-child edge.

Auto-close: CloseRequest.AutoCloseMolecule and
CloseBatchRequest.AutoCloseMolecule (opt-in, so gc's own auto-close is
not doubled) close the molecule root a close completed IN THE SAME
TRANSACTION, unforced and guarded on the root revision read there:
storageissueops.CloseCompletedMoleculeInTx on the store backends (the
role bodies bound to the caller's tx, TxMoleculeReader) and
uow.CloseCompletedMoleculeInUOW on the unit of work. It replays on an
idempotent re-close, reports the root on CloseResult/CloseOutcome
.AutoClosedMolecule, and a root its own close policy refuses stays open
and is reported (MoleculeAutoCloseRefusal) without failing the step.

Advance: a new MoleculeStepper role (storage.DoltStorage accessor,
uow.MoleculeStepperSource) whose one implementation,
issueops.NewMoleculeStepper, claims the next ready step through the
Claimer (Lifecycle.Update's Claim for a wisp step): assignee set, a step
another actor holds skipped, never taken.

HTTP: closeIssue/batchCloseIssues carry auto_close_molecule behind the
issues.close.autoCloseMolecule behavior token, and POST
/v0/beads/issues/{id}:advanceMolecule (issues.advanceMolecule) serves
the stepper. Handlers only decode, call the role and encode. The client
sends the member and dials the operation only where advertised; against
an older server it DEGRADES rather than refuses — it runs the same
library rule over its own roles (issueops.CloseCompletedMolecule after
the close, NewMoleculeStepper for the advance), so the outcome is the
same in more round trips. The capability fallbacks that lived in
cmd/bd move into the client: BatchGetter answers one getIssue per id
without issues.batchGet, and EdgeReader splits past the operation's 100
anchors.

Conformance: RunMolecule* on dolt, embedded, uow and http (the http leg
twice: served, and against a server with the tokens struck out).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(cmd/bd): molecule commands and create --parent through the library entries

`bd close`, `bd close --continue`, `bd mol current`, `bd mol progress`,
`bd ready --mol` and `bd create --parent` now call the one library entry
for each rule on every route (direct, proxied server, remote):

- close (batch, --if-revision, proxied) sets CloseRequest/
  CloseBatchRequest.AutoCloseMolecule and only reports what the library
  closed in the step close's transaction. autoCloseCompletedMolecule,
  autoCloseProxiedCompletedMolecule and closeCompletedMoleculeRoot are
  gone, and so is the separate post-close write.
- --continue is the route's MoleculeStepper role: a real claim (the
  assignee is set) that skips a step another actor holds. Before, the
  direct and http routes flipped the status only and could take it.
  AdvanceToNextStep, ClaimStepIfOpen and its two implementations are
  gone.
- mol current / mol progress / ready --mol read through
  issueops.ViewMolecule, ReadMoleculeProgress, ActiveMoleculeIDs and
  LoadMolecule/AnalyzeMolecule over the route's roles. Over http this
  fixes the missing step assignee on `ready --mol` (corpus mark
  mc-ready-mol). The proxied route's SearchIssues fallback, the role
  store, the third progress count and the cmd/bd copy of the readiness
  analysis are deleted; only presentation stays here.
- create --parent asks the create role to mint the child id on every
  route (the local CLI reservation is gone) and to inherit the parent's
  labels (InheritLabelsFromParent) inside the create. The dry-run
  preview still shows the labels, and a failed label read there is
  reported, not swallowed.

TestProxiedServerMoleculeLifecycleAgreesOnEveryRoute runs one molecule
lifecycle through the real binary on the direct, proxied and remote
(`bd connect` to `bd serve`) routes and requires the same rows and the
same JSON on all three. The served e2e now also pins the held-step skip,
the claimed step's assignee and the full rows of `ready --mol`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(httpclient): refuse molecule auto-close and advance before dialing an older server

The client used to DEGRADE against a server without
issues.close.autoCloseMolecule / issues.advanceMolecule: it closed the step
without the member and ran a second, client-side copy of the auto-close
(issueops.CloseCompletedMolecule) in its own transactions, and composed the
stepper over its own roles. That kept two executions of each rule alive.
Now the rule runs in ONE place, the server's library: a close or batch close
that sets AutoCloseMolecule, and an Advance, refuse before anything is dialed
with the typed capability error (storage.ErrUnsupported, Capability naming the
token). The composed single-item batch leg now carries the member too.

- issueops.CloseCompletedMolecule (the role-composed form) is gone.
  MoleculeRootClose is the one root close request (unforced, the auto-close
  reason, the session, guarded on the root revision read), and both
  in-transaction bodies (storage issueops CloseCompletedMoleculeInTx, uow
  CloseCompletedMoleculeInUOW) build from it.
- MoleculeView.Ready is `bd ready --mol`'s list (every analysis-ready node,
  hydrated), so ready --mol and mol current derive from ViewMolecule alone.

Tests: unit pre-dial refusal and member pins (httpclient molecule_test.go),
TestServedMoleculeRefusesAgainstAnOlderServer (step stays open, nothing
claimed) replacing the degraded contract arm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cmd/bd): ask for the molecule auto-close only where the route serves it

The refuse-before-dialing client made every `bd close` over http fail
against a server that does not advertise issues.close.autoCloseMolecule
(an older bd serve, or the MC server shape, whose orchestrator owns the
molecule lifecycle): the CLI always set AutoCloseMolecule.
storage.ServesMoleculeAutoClose answers, through every decorator, whether a
store's closes may carry the flag (MoleculeAutoCloseProber, implemented by
httpclient.Store from its handshake; every local backend serves it). The
direct batch close and the --if-revision close set the flag from it; the
proxied route always serves it. Against a silent server the close goes out
without the member and the server's side owns the auto-close.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(backend/http): scope the advertised-policy check to reads before the close

The close policy check is the client-side policy's last chance: it runs
before the close request, so only the reads up to that request count. A
read after the close (the old-server molecule notice reads the closed
step's edges) is not the external-dependency policy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(backend/http/corpus): drop the six marks S16 and S19 retire

With the molecule library entries underneath, mol current (with and
without an id, json and text), mol progress and ready --mol read through
issueops.LoadMolecule over the roles, and create --parent lets the server
mint the child id. Those six shapes pass on the reference profile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cmd/bd): never silent against a server without the molecule tokens

Against a server that advertises neither issues.close.autoCloseMolecule
nor issues.advanceMolecule (an older bd serve, or one whose orchestrator
owns the molecule lifecycle):

- `bd close --continue` closed the step and only then found the advance
  refused, leaving the step closed and the next step unclaimed. It now
  asks storage.ServesMoleculeAdvance (a MoleculeAdvanceProber the http
  store answers from its handshake; local backends always serve it)
  BEFORE the close and refuses up front, saying nothing was closed.
- `bd close` went out without auto_close_molecule and said nothing. When
  the closed step belongs to a molecule (issueops.MoleculeRoot), a notice
  on stderr now names the molecule and the missing token: its auto-close
  is the server's to run. The batch and --if-revision closes both say it.

The served e2e masks both tokens out of the handshake and checks the
up-front refusal (the step stays open) and the notice; the httpclient
unit test pins ServesMoleculeAdvance to the handshake.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(cmd/bd): mol show through issueops.LoadMolecule on every route

`bd mol show` still loaded the molecule through cmd/bd's
loadTemplateSubgraph (raw GetIssue, GetDependentsWithMetadata and
GetDependencyRecords, plus an id-pattern child probe), while mol current,
mol progress and ready --mol read through the library. It now loads
through issueops.LoadMolecule over the route's molecule roles (the direct
store's, or the proxied provider's), so membership is the parent-child
edge everywhere and the http route reads through roles the server serves.
The served e2e checks mol show's root and step count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: the molecule auto-close fails the step's close on a non-policy error; stale comments

CloseRequest.AutoCloseMolecule and CloseCompletedMoleculeInTx now say what
changed when the auto-close moved into the close's transaction: a root
close the close policy refuses still leaves the root open and is reported,
but any other failure (a storage error, a lost race on the root's revision)
fails the step's close with it, where the CLI used to close the root
afterwards and only warn.

Stale: the advanceMolecule vocabulary entry said the client composes the
stepper over its own roles when unserved (it refuses before dialing), and
the graph-create collision probe called itself best-effort by transport
(the http GetIssue miss is storage.ErrNotFound like every other store's).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changelog): the molecule tokens and the S16/S19 behaviours

Entries for issues.close.autoCloseMolecule and issues.advanceMolecule, the
issueops molecule entries, the auto-close inside the step's close (and a
non-policy failure of it failing the close), the real claim behind
close --continue, the molecule reads on every route, the notice and the
up-front --continue refusal against a server without the tokens, and
create --parent / mol reads over http.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(httpclient): regenerate unsupported_gen.go for MoleculeStepper

The PR adds MoleculeStepper() to storage.DoltStorage (200 -> 201
methods). httpclient implements it by hand, but the generated shell's
trailer still counted 200, so
//internal/storage/unsupportedgen:unsupportedgen_test
(TestGeneratedShellIsFresh) failed in Bazel / test and
Bazel / integration, turning CI Gate / Required red.

Regenerated with `go generate ./internal/httpclient`; the only change
is the trailer count (143 of 201 methods generated; 58 left).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(molecule): auto-close refusals, write skew, close --json, docs

Review fixes for #7513, numbered as in each iteration's review
synthesis.

Iteration 1:

F1: a close guard's refusal of the root (TemplateReadOnlyError,
PinnedError, CloseNotAssigneeError) is an auto-close refusal, like the
close policy's: the root stays open and is reported, and the step's
close stands. Pinned by the new conformance case
RunMoleculeGuardedRootKeepsTheStepClose on dolt, embedded, uow and the
served http client.

F2: two closes that finish a molecule's last two steps in concurrent
transactions each read the other's step as open, so neither closed the
root and both committed. Every auto-close now rewrites the root's
coordination cell before it decides the root (local_metadata
molecule-coordination/v1/<shard>, the dependency coordination idiom and
sharding with a FreshRowLock value), in both twins
(CloseCompletedMoleculesInTx and CloseCompletedMoleculesInUOW). Two
deciders of one root now conflict at commit (1213), and the retry reads
the winner's close and closes the root. This is the synthesis's option
(c), applied through a coordination cell instead of the root row; it
needs no post-commit second transaction and no engine lock. The
deterministic two-transaction regression fails without the touch and
passes with it on dolt and uow; the concurrent-close tests end with the
root closed in every round, reported by exactly one close.

F3: the auto-close checks the root's eligibility before walking any
step, MoleculeStepsClosed stops at the first open step, and a batch
decides each root once and reports it on the first item under it.

F4: ErrVersionMismatch on the root is not a refusal; it fails the
step's close with it. The classifier unit test pins this. A conformance
case cannot stage that race deterministically through the public roles.

F5: storage.ServesMoleculeAdvance answers (bool, error), and bd close
--continue refuses before closing anything when the handshake cannot be
read.

F6: the CHANGELOG and the stepper and batch-closer doc comments say
what the code does.

F7: the unserved-auto-close notice fires only when the close left an
auto-closing molecule with every step closed and its root open
(issueops.CompletedMolecule): again on a re-close, once per root in a
batch, never for a step under an ordinary epic or an unfinished
molecule. Proxied mol show, mol current and mol progress again report a
read unit of work that cannot be opened as itself, not as a molecule
that was not found.

F8: the write-ledger comment says the close is refused before dialing.
The dead FirstClosed/LastClosed guards in mol progress pre-exist on main
and are left as they are.

Iteration 2:

F1: on the proxied route, bd ready --mol reported a read unit
of work it could not open twice: once as itself, then as "molecule
'<id>' not found", which under --json is a second error document on
stdout. It now returns moleculeNotResolved, as mol show, mol current and
mol progress do. TestProxiedReadyMolReportsAnUnopenableReadOnce drives
runMoleculeReady with a provider whose NewUOW fails and wants one Error:
line, or one JSON document; both subtests fail with the old return.

F2: the coordination cell serializes every concurrent close of a step
under an open auto-closing root, not only the closes that finish the
molecule. That is the price of deciding the root in the step's
transaction, so it is documented (TouchMoleculeCoordinationInTx, the
UOW twin, CloseRequest.AutoCloseMolecule, the CHANGELOG) and pinned on
dolt and uow: two sibling closes with a third step still open conflict
(both commit when the touch is removed, on either twin), and a six-step
fan-out closes every step through the store's retry, with the root
closed and reported by exactly one close. The synthesis's alternative,
a post-commit recheck by any close that read a step open, is not taken:
it is a second, best-effort transaction after the step's commit, the
shape this PR exists to remove.

F3: MoleculeRootClose's doc no longer promises that a step reopened
between the completion read and the root close fails the step's close.
The guard is the root's RowVersion, which a step reopen never writes;
the doc now says what the guard covers and that this race goes
undetected (it is inherited from the CLI's old post-commit auto-close).

F4: the user docs describe the auto-close. docs/workflows/molecules.md
replaces "Closing the last child does not close the molecule root"
with which roots close and which stay open, the refusal warning, the
unserved-server note and the --json members, and documents the claiming
--continue and parent-child step membership;
docs/reference/json-schema.md gains a bd close --json section. These
are main-only behaviors on pages pinned to v1.2.2 (docs/cli-docs.pin):
a maintainer call against §1 of
engdocs/decisions/2026-07-17-docs-release-pin.md, as in #6508, #5855,
#5997 and #5092. The auto-close itself shipped in v1.2.2
(cmd/bd/close.go autoCloseCompletedMolecule), so the old sentence was
already wrong at the pin. docs/cli-reference/ is generated from the
pinned release and is not hand-edited; the bd close and bd mol show
help texts carry the same facts and reach it at the next pin bump.

F5: bd close --json reports the auto-close. The entry of a close that
completed a molecule gains auto_closed_molecule (the root it closed) or
molecule_auto_close_refusal (why the root stayed open), the HTTP API's
names, on the direct, proxied and --if-revision routes. The members sit
beside the issue's own rather than wrapping the output in an object the
way --suggest-next does: an object would change the output's shape
exactly when a close completes a molecule and break every consumer that
reads an array, while members leave each entry decoding as the closed
issue, compose with `closed` under the flag objects, and leave a plain
close's bytes unchanged. Pinned on the embedded and proxied tiers
(TestEmbeddedCloseJSONReportsMoleculeAutoClose, TestProxiedServerClose2B
json_reports_*, and both --if-revision replay tests), all red without
the change.

F6: cmd/bd's BeadsTemplateLabel is issueops.MoleculeTemplateLabel, so
the template commands and molecule membership cannot drift apart.

F7: the UOW twin's revision probe says that it writes nothing,
and the BatchCloseRequest.auto_close_molecule spec description has its
verb back (apigen regenerated, no drift).

Iteration 3:

F1: on the unit-of-work route (bd serve, the proxied CLI), a refused
root's molecule_auto_close_refusal and warning carried the use case's
and repository's wrapping ("close <id>: db:
IssueSQLRepository.CloseChecked <id>: ...") around the refusal, where
the tx twin and the docs give the refusal alone. Both twins now report
it through RefusedMoleculeAutoClose, which answers the refusing guard's
or policy's own sentence. RunMoleculeRefusedRootKeepsTheStepClose,
RunMoleculeGuardedRootKeepsTheStepClose and the embedded and proxied
close --json tests want that exact sentence; the uow conformance leg
and the proxied test fail without the unwrap.

F2: the docs no longer promise ErrVersionMismatch for a write to the
root that races its auto-close. The root's read and its revision check
share one transaction snapshot, so that write conflicts with the root
close at commit and the retry decides the root again; the close fails
only if it still conflicts when its retry budget runs out
(MoleculeRootClose, IsMoleculeAutoCloseRefusal,
CloseRequest.AutoCloseMolecule, the tx twin's comment, the CHANGELOG
and the OpenAPI description, apigen regenerated).

F3: TestEmbeddedCloseJSONReportsMoleculeAutoClose moves above
TestEmbeddedCloseConcurrent's doc comment, which documents its own test
again.

F4: bd mol progress counting direct steps while the auto-close counts
every descendant predates this PR; it is left for a follow-up.

F5: cmd/bd's molReader drops GetMoleculeProgress, which nothing called
once mol progress read through issueops.ReadMoleculeProgress.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 19:50:34 +00:00

588 lines
29 KiB
Go

// Package issueops declares the public values used for guarded issue mutations.
//
// # Stability
//
// EXPERIMENTAL. This package is not yet covered by the project's compatibility
// promise and may change in a minor release. Pin an exact beads version.
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.
//
// The VALUES an edit carries answer to the same field rules a create's labels
// do: a label longer than the column is refused with ErrFieldTooLong and the
// whole update writes nothing. Repetition is free in both directions — the
// same label named twice in one edit is applied once, and removing a label the
// issue does not carry is a no-op that reports Changed false.
//
// An EMPTY-STRING entry is DROPPED — not written, and not refused. A label
// row carrying "" renders as nothing and matches nothing, so writing one only
// stores junk; refusing the whole update would let one stray entry fail an
// otherwise-good multi-label edit. Dropping is a no-op rather than a partial
// write: an Add carrying only "" changes nothing and reports Changed false.
// An empty entry already stored is left alone by Add and Remove and cleared by
// a Replace that omits it, which is the ordinary set behavior and not a
// migration.
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.
//
// CLEARING STORES THE EMPTY JSON DOCUMENT. An issue's metadata is never
// SQL NULL, and it is never NULL at creation either, so "created with no
// metadata" and "given metadata and then cleared" are the SAME stored
// value rather than two states for one user-visible fact. A consumer
// filtering on `metadata IS NULL` therefore matches neither, and one
// asking for an empty document matches both.
//
// Read back through a result or the Reader role, that same empty document
// arrives as an EMPTY json.RawMessage rather than the two bytes of an
// empty object — so a caller must treat nil, empty and {} as one value on
// the way out, exactly as this field treats them on the way in.
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. An empty Issue.CreatedBy defaults to
// Actor (the same rule for every create shape, batch items included).
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
// IDPrefix is the prefix an explicit Issue.ID is checked against, and it
// OVERRIDES the one the substrate has configured. Empty means "use the
// substrate's", which is the ordinary case.
//
// It exists because the workspace's own config.yaml `issue-prefix` wins
// over the database's (GH#4957) and no implementation can see config.yaml
// — a shared server's database knows only its own prefix. Resolving that
// is the front door's job, the same way DeleteRequest.IDs are exact
// because resolution belongs to the front door; the role enforces what it
// is handed. Without it the two `bd create` routes disagree about which
// ids a workspace may mint.
IDPrefix string
// DefaultPriority says the caller has no priority for the issue, and the
// create stores DefaultCreatePriority. It exists because Issue.Priority
// cannot say "absent": its zero value is P0, a real and urgent priority, so
// a caller that leaves it unset asks for critical work. The default is
// applied here, once, for every route — the CLI's `bd create` without
// --priority and an HTTP create without `priority` both set this rather
// than spelling the number themselves.
//
// Issue.Priority must be zero when it is set; a request that sets both is
// ErrValidation, because the two would disagree about what was asked for.
DefaultPriority bool
}
// DefaultCreatePriority is the priority a create stores when its request sets
// DefaultPriority (CreateRequest, BatchCreateItem, CreateItem): P2, medium.
const DefaultCreatePriority = 2
// 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
// ForceNotesOverwrite bypasses only the refusal on a Patch.Notes that is a
// NotesReplacement of the existing notes — replacing non-empty notes with
// different non-empty content; an explicit clear is not fenced. The zero
// value enforces the fence. It has no effect without such a Patch.Notes edit, and
// a request that sets it with no Patch.Notes is invalid. It is independent
// of ForceAssigneeTransfer and ForceClosePolicy — neither bypasses this, nor
// does this bypass either of them — and, deliberately, of ExpectedAssignee
// too: a caller pairing a notes edit with an assignee compare-and-set still
// needs this bit to overwrite notes, and setting it never touches the
// assignee guard. A command adapter with a single --force flag therefore
// maps that flag to all three fields, conditioning this one on a
// Patch.Notes edit.
ForceNotesOverwrite 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
// AllowTemplate says the caller edits a template deliberately, so the
// template read-only refusal (*TemplateReadOnlyError) stands down for this
// request. bd label and bd set-state set it to keep their pre-guard
// behavior: they have always written to templates. The zero value
// enforces the guard. It bypasses nothing else — validation, the
// preconditions, the assignee and notes fences and close policy still
// apply — and has no effect on an issue that is not a template.
AllowTemplate bool
// The three Expected* guards below are this package's FOUNDING spelling of
// the compare-and-set family, and the family's rules are stated once, at
// length, on DeleteRequest.ExpectedVersion (deleter.go) and
// ApplyUpdateItem's guards (batchapplier.go). They hold here unchanged and
// are not restated:
//
// - THE TOKEN IS OPAQUE AND COMPARED FOR EQUALITY ONLY. RowVersion is
// minted afresh on every lifecycle write rather than incremented, so
// "newer" and "older" are not questions a version guard can answer.
// - IT GUARDS THE ROW'S LIFECYCLE STATE, NOT ITS GRAPH. RowVersion is
// reminted by status, assignee and started_at writes and deliberately
// not by label, dependency, rename or is_blocked writes, so a matching
// token does not promise the row's edges are the ones the caller saw.
// - nil DISABLES THE CHECK. Each is a pointer so that "do not check" is
// distinct from a caller requiring the never-written version 0, or the
// empty assignee, which is a real guard meaning "expected unassigned".
// - GUARDS PRESENT TOGETHER MUST ALL HOLD, and each is read inside the
// writing transaction, so there is no internal TOCTOU.
// - A MISS REFUSES AND WRITES NOTHING, with the typed sentinel for the
// guard that missed: ErrVersionMismatch, ErrStatusMismatch,
// ErrAssigneeMismatch. That is the opposite of MetadataCAS, whose miss
// is a result rather than an error; metadatacas.go states why.
//
// 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.
//
// THE COMPARISON IS SEPARATOR-INSENSITIVE, exactly as
// ReleaseRequest.ExpectedAssignee documents: a run of ".", "_" or "-"
// matches any other such run — except an exact "--" run, which decodes to
// "/" as gascity's rig-qualified agent encoding, so "a--b" matches "a/b"
// rather than "a__b" — and nothing else is forgiven.
ExpectedAssignee *string
// ExpectedStatus requires the current status to match. It must be nil when
// Claim is true.
ExpectedStatus *Status
// IssuePlaneOnly restricts the update to the issue plane: an ID that names
// a wisp is ErrNotFound rather than an ephemeral row to update. The zero
// value keeps the both-plane auto-resolve every caller gets today.
//
// Resolution happens INSIDE the transaction the update runs in, so a
// caller cannot be handed the plane an earlier read saw. It exists for the
// surface that serves durable issues only — refusing there rather than
// carrying a private copy of the resolve is what keeps the two front doors
// on one implementation.
IssuePlaneOnly bool
// Provenance labels the version-control history entry this mutation
// records, naming the surface the update came from. Empty selects the
// implementation's default label.
//
// It NEVER changes WHETHER history is recorded — only how the entry reads.
// An update that records none records none with it set, one that records
// one records one with it empty, and an implementation with no history to
// label ignores it. Persistence, not this, is what decides whether an issue
// is versioned at all.
Provenance string
}
// CloseRequest describes an issue closure.
type CloseRequest struct {
Actor string
IssueID string
// Reason records why the issue was closed. It is stored on the issue and
// read back on CloseResult.Issue.CloseReason, alongside the ClosedAt the
// same close stamps.
//
// THE FIRST CLOSE WINS. A second Close of an already-closed issue is the
// no-op CloseResult.Changed describes, so it writes neither this nor
// Session and the stored pair keeps the values the first close gave them
// — a replayed close cannot rewrite the record of why the work ended. A
// Reopen clears both, because they describe a closure that no longer
// holds.
Reason string
// Session names the working session that closed the issue. It is stored
// and read back on CloseResult.Issue.ClosedBySession, under the same
// first-close-wins rule as Reason.
Session string
// Force bypasses blocker and open-child close policy and the two close
// guards a force has always waived in bd: the pin, and the assignee
// authority fence. It never bypasses the template guard, validation,
// ExpectedVersion, or lifecycle rules.
Force bool
// ExpectedVersion requires the current row version to match, and is checked
// BEFORE the idempotent close — so a re-close of an already-closed issue
// still refuses on a stale token rather than reporting the no-op it would
// otherwise be. That ordering is the whole difference from composing a read
// with a close, and a conformance case pins it.
//
// The rest of the family's rules are UpdateRequest.ExpectedVersion's,
// unchanged: the token is opaque and compared for equality only, it guards
// the row's lifecycle state and not its graph, nil disables the check, and
// a miss refuses with ErrVersionMismatch having written nothing. Force
// bypasses close policy and never this guard.
ExpectedVersion *int64
// AutoCloseMolecule closes the issue's molecule root IN THE SAME
// TRANSACTION when this close completed it: the root closes itself when
// complete (AutoClosesWhenComplete), it is open, and every step under it
// is now closed (CompletedMolecule). The root close is unforced, guarded
// on the root revision read inside that transaction, and records
// MoleculeAutoCloseReason and this request's Session.
//
// It runs for an idempotent re-close too: the rule is state-derived, so a
// replayed close of the last step heals a root a crash left open.
//
// IT IS OPT-IN because an orchestrator may run its own molecule
// lifecycle (gc closes molecule roots itself); the zero value never
// touches a root. A root close its close policy refuses (a live blocker
// on the root, open children) or a close guard refuses (a template root, a
// pinned root, a root assigned to someone other than Actor — the root
// close is unforced, so each guard holds as it does for a direct close)
// leaves the root open and is reported on
// CloseResult.MoleculeAutoCloseRefusal (IsMoleculeAutoCloseRefusal); it
// never fails the step close.
//
// ANY OTHER FAILURE OF THE ROOT CLOSE FAILS THE STEP'S CLOSE. A storage
// error is returned and rolls the step's close back with it, so a retry
// re-runs both. (The CLI used to close the root after the step's close had
// committed and only warned when that failed, leaving a complete
// molecule's root open.) A write to the root that races this close is not
// such a failure: the two conflict at commit, and the backend's retry
// decides the root again (MoleculeRootClose).
//
// Two closes that finish a molecule's last steps concurrently do not
// strand its root: each close that decides a root first rewrites one
// coordination cell for it, so their transactions conflict at commit and
// the one that retries reads the other's close and closes the root.
//
// THE CELL SERIALIZES SIBLING CLOSES. Every close under an open
// auto-closing root rewrites it, whether or not that close completes the
// molecule, so any two concurrent closes of steps under the same root
// conflict and one of them retries. Under heavy fan-out a close can spend
// its whole retry budget conflicting and then fails with the
// serialization error. Closes under different roots contend only when
// their roots hash to the same cell.
AutoCloseMolecule bool
}
// 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.
//
// WHERE it is recorded is the issue's EVENT HISTORY, carried on the
// reopened entry the move itself records. It is not stored on a field of
// the issue and ReopenResult does not surface it, so a caller that wants
// it back reads the issue's events — the same place the Actor attribution
// for the reopen lives. A reopen with no reason still records that entry;
// it simply carries none.
Reason string
// ExpectedVersion requires the current row version to match and is checked
// before a non-done no-op.
ExpectedVersion *int64
// Provenance labels the version-control history entry this reopen records,
// naming the surface it came from. Empty selects the implementation's
// default label, and the implementations do not agree on what that is — the
// store-backed ones write "bd: reopen issue" and the unit-of-work one
// "reopen issue", neither naming the issue. A caller that wants one entry
// no matter which backend served it spells one, exactly as
// UpdateRequest.Provenance describes.
//
// It NEVER changes WHETHER history is recorded — only how the entry reads.
Provenance string
}
// 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
// AutoClosedMolecule is the molecule root CloseRequest.AutoCloseMolecule
// closed in this close's transaction, as a post-close snapshot with
// labels. Nil when nothing was auto-closed.
AutoClosedMolecule *Issue
// MoleculeAutoCloseRefusal says why a completed molecule's root stayed
// open: its close policy or a close guard refused it
// (IsMoleculeAutoCloseRefusal), in that refusal's own message, the same on
// every backend. Empty otherwise.
MoleculeAutoCloseRefusal string
}
// 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.
//
// EVERY VERB HERE MAINTAINS BLOCKED STATE under BlockedStateInvariant: a
// Create that carries edges, and an Update or Close or Reopen that moves a
// status across the closed/pinned boundary, leave the column settled for every
// row their mutation could have affected before the transaction commits.
//
// 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 Claim that loses its
// compare-and-set returns *ClaimConflictError carrying the state that beat
// it. An update of a template returns *TemplateReadOnlyError whatever its
// patch and force flags, unless it sets AllowTemplate — templates are
// read-only — checked after the
// compare-and-set preconditions, so a stale guard still reports the
// mismatch. 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. A close of an issue that is not already closed answers
// to the close guards before close policy: a template returns
// *TemplateReadOnlyError, forced or not; unforced, a pinned issue returns
// *PinnedError and one assigned to someone other than Actor (compared
// separator-insensitively) returns *CloseNotAssigneeError, matching
// ErrNotOwner. An unforced close with open children returns
// CloseOpenChildrenError without mutation. Force bypasses the pin, the
// assignee fence, and 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