* feat(http): serve list/show counts/dep tree/ping, close+reopen under a session, one-lookup not-found (S6b/S6c/S6d) S6c. The external-dependency decorator rebuilt its role views from the legacy DoltStorage seam (storereader over itself, IsBlocked, GetDependencyTree, ClaimReadyIssue), which a remote store only partly serves: `bd list`/`bd children` refused on the SearchIssuesWithCounts stub, `bd show --json` printed zero counts, the default `bd dep tree` refused, `bd ready --claim` and `bd close` of an externally blocked issue reached unsupported paths. For a storage.RemoteBackendStore each view now passes the inner role through and lays the policy over it in role terms (externaldeps/remote_roles.go): ready reads and the ready claim exclude the workspace-wide blocked set over a widened window; per-issue checks (claim, close, batch close, list annotations, tree leaves) read only the named issues' edges through EdgeReader instead of every edge in the workspace. A server advertising policy.external_dependencies (MC's does) gets a plain passthrough. `bd ping` uses a new storage.Pinger, which the http store answers with its authenticated context read. S6d. A store reporting storage.CallerAttributionLimitedStore (http) cannot carry a Provenance label or a patch's closed_by_session. The library still refuses both; the CLI omits them where nothing is lost: `bd reopen`'s fixed "bd: reopen <id>" label (the server labels the same entry), and the closed_by_session of `bd update -s closed` (attribution only, usually the ambient CLAUDE_SESSION_ID; an explicit --session prints a notice; `bd close` still records it). See cmd/bd/remote_backend.go. S6b. utils.ExactIDLookupStore: the resolver stops at exact lookups for a store with no substring search, so a missing prefixed id is a not-found (beadserrors.ErrNotFound, "no issue found matching") after one getIssue. The general resolver no longer repeats an identical normalized probe. The http SearchIssueIDs answers D11's partial-id refusal, which now unwraps to ErrNotFound. Contributor auto-routing for a remote workspace reads local config only, so the not-found fallback pays no settings round trip. `bd update <absent> --claim` (gc's hook claim) answers a gc-classifiable not-found in at most two requests. Served e2e (backend/http/e2e_remote_roles_test.go): every gc list shape and `bd children` against embedded, `show --json` count parity, default dep tree parity, external blocking still enforced, close/reopen under CLAUDE_SESSION_ID, missing-id request counts, absent-id claim against the current server and the MC handshake mask, policy passthrough under the MC mask, ping. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(externaldeps): role-level remote reader and claimer cases bd ready and bd update --claim reach the policy through the legacy seam and the lifecycle guard, so the remote Reader.Ready exclusion and the remote Claimer guard (what bd serve and library callers reach) are pinned at the role level with a fake remote store. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(http): bd serve advertises policy.external_dependencies; clients pass through bd serve composes every ready, claim, claim-next, close, blocking and tree role through the external-dependency policy, but never said so. Every client therefore ran the policy a second time, with the CLIENT machine's external-project config, and claim-next became a non-atomic read-then-claim loop on the client. The server now advertises the token exactly when the roles it serves were composed through the policy: httpapi.Config.ExternalDependencyPolicy, which bd serve derives from its actual chain (externaldeps.Applied for the store arm, externaldeps.AppliedToProvider for the provider arm). A server handed raw roles still withholds it, so the token stays truthful. Against a server that advertises it, every remote role view hands the request to the server's own role untouched: no client validation, no edge reads, claim-next is the server's one atomic call, and the ready count is the server's countReadyWork (new remoteReadyCounter). The client-side policy remains only for servers that do not advertise the token. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(create): default created_by to the request's actor in the create role created_by was stamped in two front doors and never in the library: the CLI (creationActorStamp, with a remote-workspace special case) and the three httpapi create handlers. A library caller of Lifecycle.Create or BatchCreator with an empty CreatedBy stored "" locally and the actor over http. PreparePublicCreateRequest, which every create shape prepares through (Lifecycle.Create, BatchCreator items, batch-apply create items), now defaults an empty CreatedBy to request.Actor; an explicit value is kept. The handlers no longer stamp, `bd create` and the state event create pass only the actor, and creationActorStamp/isRemoteBackendWorkspace are gone. The CLI sites that still create through the raw CreateIssue seam (swarm, todo, gate, the create form) keep stamping currentActor(): that seam is shared with import, where defaulting would re-attribute imported rows, and the http store refuses it anyway, so the remote special case was never reachable there. Conformance: the lifecycle-create, batch-creator and batch-apply contracts now pin created_by == actor for an item that names none, on every leg. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(httpclient): GetIssue answers a miss with storage.ErrNotFound, like the local stores The http store's raw GetIssue answered a missing id with (nil, nil), where DoltStore and the embedded store return a wrapped storage.ErrNotFound. A caller written against the backend contract read the http miss as a hit: `bd create --graph` refused every explicit-id plan over http (patched in cmd/bd on feat/http-mc-corpus; that workaround is reverted there). GetIssue now returns the miss (and the empty id) as storage.ErrNotFound, spelled as issueops.GetIssueInTx spells it. GetLabels, which reads through GetIssue, keeps the local read's "no labels" answer for a missing id; the `bd list --parent` walk reads the typed miss as "parent issue not found". The served bridge test now holds the local reference store and the http store to the same miss: ErrNotFound with the same text. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(createbatchequiv): re-record the apply golden for the created_by default c2866ea7fe made the create role default an empty CreatedBy to the request's actor, so every create item of the apply scenario's batch (actor "apply-writer") now stores created_by "apply-writer" instead of "". TestCreateBatchFastPathsMatchPerRow_*/apply compared the stored rows to a digest recorded before that change and failed on exactly the three tables the column reaches: issues and wisps (the row) and events (the update event's old-value snapshot). Fast and per-row bodies still agree; the batch-apply conformance contract pins the same value. Bisected with bazel: passes at be92efe40f's integ twin 696f7acc8e, fails from the created_by commit on. Only apply.json's three digests move. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * style: gofmt ledger.go and the externaldeps remote-roles test Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cmd/bd): bd create reads routing settings local-only on a remote backend too determineAutoRoutedRepoPath skipped a remote backend's settings document (routing targets are local paths that one shared document cannot name for every client), but getRoutingConfigValue, which `bd create` and migrate-personal read routing.* and contributor.* through, still asked it. The same workspace could route a create one way and a lookup another, and every create paid a settings round trip per key. Both now go through routingSettingsStore: nil for a remote backend, so routing comes from config.yaml / the environment only there, and a local store is still consulted. A unit test holds both reads to the rule with a store that counts settings reads. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cmd/bd): say so when update -s closed drops an ambient CLAUDE_SESSION_ID Over http `bd update -s closed` cannot carry closed_by_session, so the CLI drops it rather than refusing the close. An explicit --session printed a notice; the ambient CLAUDE_SESSION_ID every agent under Claude Code exports was dropped without a word, a silent data difference from a local backend (the served corpus's mc-update-meta-status-closed). The drop is now named on stderr in both cases, once per command, pointing at `bd close`, whose wire operation records the session. The served e2e asserts the notice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(backend/http): hold bd list --limit 2 to each side's own unlimited order TestE2E_ListWithGCFiltersMatchesEmbedded compared the --limit 2 rows of the served and embedded workspaces as sets. The seed has four P2 rows, so the limit cuts a priority tie whose created_at order differs between two workspaces seeded seconds apart: a test-only flake, the order itself being total. Each side's two rows must now be, in order, the first two of that same side's --limit 0 listing; the unlimited listings are still compared across sides by the shape loop. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test: unit-tier pins for the created_by default, the policy token and the GetIssue miss Three review mutations were caught only by a heavier tier (the uow conformance legs, the served httpclient tier) or by one package's test alone. Each now has a unit test where its rule lives: - issueops: PreparePublicCreateRequest defaults an empty CreatedBy to the actor and keeps an explicit one, without mutating the caller's request. - externaldeps: the policy layer AppliedToProvider finds becomes the handshake's policy.external_dependencies through httpapi.Listen, the composition bd serve performs, and a raw provider's handshake lacks it. - httpclient (no embedded engine): GetIssue over the real wire client against a stub server answers a 404 not_found, and the empty id without dialing, as storage.ErrNotFound spelled like the local stores. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(changelog): S6b/c/d entries match the code The S6 entry still said `bd create` suppresses created_by on a remote workspace and that the external-dependency policy runs client-side. Since S6b/c/d, created_by defaults to the actor in the library on every backend, and every bd serve composed through the policy advertises policy.external_dependencies, so clients pass those operations through; the client-side policy (now in role terms) runs only against a server that does not advertise it. New entries: the advertised policy token, bd ping over http, the created_by library default, closed_by_session dropped by an http `bd update -s closed` (with a notice, typed or ambient), reopen without a Provenance label over http, local-only routing.* / contributor.* on a remote backend, GetIssue's miss as storage.ErrNotFound, and list/children/show counts/dep tree over http. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(externaldeps): keep S6's list --ready, --claim-next refusal and lost-race error on the S6c composition The re-adopted S6 head (#7288) carries the review fixup's remote role composition; S6c replaces it with its own (rolesAreRemote, the widened ready window, the policy passthrough). Two behaviours S6 shipped and its reviews pinned would otherwise go: - bd close --claim-next against a server that does not apply the policy is refused whole, before anything is read or closed, with "the served batch close cannot carry a next claim, so nothing was closed; close without --claim-next, then run `bd ready --claim`". S6c passed the batch to the http closer, whose W-CloseBatchRequest.ClaimNext refusal drops the remedy, so TestE2E_BDOverHTTP's two refuseClaimNext steps went red. A request invalid on every backend is still ErrValidation first, and a server that applies the policy still gets the request untouched. - remoteReadyClaimer.ClaimNext reports a page on which every candidate was lost to another actor as "claim ready: lost N races ...", not as the empty answer that means there is no work. - `bd list --ready` (List with ReadyFlag) is answered by the policy store's own reader over the served ready reads, as S6 does. S6c passed it to the served listing, which cannot carry ReadyFlag (httpclient ledger row E-ListRequest.ReadyFlag), so it exited 1 over http with or without external refs; TestE2E_BDOverHTTP and TestServedRolesKeepTheExternalDependencyPolicy were red on it. TestRemoteReaderAnswersAReadyListingWithoutTheWireFlag pins it, with the fake's served List refusing ReadyFlag as the wire does. S6's composition tests now run against S6c as remote_roles_composition_test.go. Their fake serves Ready the way a server does (the S6 composition read ready work through the legacy policy reader instead), and two call logs gain that Ready. TestRemoteBatchCloserRefusesANextClaim, TestRemoteBatchCloserValidatesANextClaimFirst and TestRemoteReadyClaimerReportsLostRaces were red on S6c before this change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(externaldeps): unassigned claim-next and fail-closed close reads Review fixes for the S6c composition against a server that does not advertise policy.external_dependencies: the two majors of review attempt 1, plus the minors on the same code. - ReadyClaimer: the composed claim-next reads only open, unassigned ready rows (Unassigned=true, Assignee cleared), the candidates the local ClaimReadyIssueInTx selects. A row another actor holds, or one already assigned to the caller, is no longer taken or counted as a lost race. Each pass reads 25 candidates past the blocked rows, as httpclient's composed claim does, and a full window lost end to end is read once more: claimed rows leave the unassigned set. Only a claim that tried candidates and won none is an error. - BatchCloser: an externally blocked item travels to the server only when its status read finds it closed or not found (liveRefusal). Any other read error is that item's outcome, so a transient or auth failure no longer forwards a refused close to a server that will not refuse it. - TreeWalker: a failed capability probe renders the external leaves over the walked tree instead of failing a walk the server already answered. appendTreeExternalReferences skips an id the tree holds, so an enforcing server's own leaves are not doubled. - remoteEdges names each anchor once and skips an empty one, which the http EdgeReader refuses with ErrValidation. The composition fakes now honor Unassigned/Assignee as workapi.BuildReadyFilter does, model a rival claim landing first and a failing GetIssue, and refuse an empty edge anchor as httpclient does. New: TestRemoteReadyClaimerTakesOnlyUnassignedWork, TestRemoteReadyClaimerWalksAContendedFront, TestRemoteBatchCloserAnswersAFailedReadWithIt, TestRemoteEdgesNamesEachAnchorOnce, and the probe-failure cases of TestRemoteTreeWalkerAddsExternalLeaves. Each is red with its fix reverted. From review attempt 2, three nearby cleanups: - TestServedRolesKeepTheExternalDependencyPolicy seeds open rows held by another actor and by the claimant ahead of the free work, then claims with and without an assignee filter. The unassigned-only claim is now pinned over a real served server, not only through the fakes: red with the pre-fixup remote_roles.go, with filter.Unassigned dropped, and (the filtered claim) with an explicit assignee honored. - The capabilities description in openapi.v0.yaml (and the regenerated types.gen.go comment) no longer calls the whole list build-level: policy.external_dependencies depends on how the server composed its roles, as the paragraph above it says. - createbatchequiv's golden note names issueops.PreparePublicCreateRequest instead of a commit id that is not on this branch. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(backend/http): count a not_found read as reaching the remote in #7469's credential doors main's #7469 added TestExplicitCredentialIgnoresTheEnvPlaintextGrant. Its OpenWith and Open doors read bd-1 from plaintextRemote, which answers every issue read not_found, and the granted leg needs that read to return a nil error. That held while the http client answered a miss with (nil, nil). This branch's "fix(httpclient): GetIssue answers a miss with storage.ErrNotFound, like the local stores" makes the same read return storage.ErrNotFound. So on main plus this branch both doors fail at per_open_credential_test.go:392 ("with Target.AllowInsecureCredential: not found: issue bd-1") under plain go test. The merge is textually clean, so only a build of the merge shows it. The two store doors now count storage.ErrNotFound as success, since that answer came off the wire. The assertions are unchanged. The refused leg still needs the "refusing to send a credential" error and no request on the transport. The granted leg still needs exactly one request carrying "Bearer explicit-token": a granted read that never reaches the wire still fails at :408. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
538 lines
26 KiB
Go
538 lines
26 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
|
|
}
|
|
|
|
// 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
|
|
}
|
|
|
|
// 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
|