beads/backend/types.go
Stephanie Jarmak c0f18bc03f
Add append-only provenance_events log and bd provenance CLI (#4461)
* Add append-only provenance_events log and bd provenance CLI

A generic primitive for capturing work provenance — the base commit a
worktree forked from, which actor touched a bead when, what landed it —
as an append-only event log keyed to an issue. Inert by default: nothing
writes it unless a producer (git hook, orchestrator, CI) opts in.

- Migration 0052: provenance_events (CHAR(36) UUID pk, FK issues
  ON DELETE CASCADE ON UPDATE CASCADE, indexes on issue_id/ref/kind).
  Sibling to events, per the wisp_events precedent for purpose-specific
  event tables rather than overloading the field-mutation audit log.
  ON UPDATE CASCADE so a bd rename (which updates issues.id in place)
  does not hard-fail the FK, matching the other aux tables (0042).
- Append-only at the event level: only record/log/by-ref operations, no
  UPDATE or DELETE of an individual event. An event's lifecycle is bound
  to its issue — removed only if the issue is deleted (ON DELETE CASCADE),
  identical to the events audit table (0005).
- Opaque actor/ref (bd never interprets them); only kind and ref_kind are
  structurally validated (ZFC). occurred_at (event-time) is separate from
  created_at (ingest-time). A reserved 'ingest-backfill' source is rejected
  so a producer cannot forge a derived event.
- Idempotent record via a content-addressed deterministic id, so a producer
  firing twice is harmless; an event with neither a ref nor occurred_at is
  rejected at the store boundary (no stable id otherwise). occurred_at is
  truncated to whole seconds for both the id basis and the stored value, so
  the id stays reproducible from the stored row (the column is bare DATETIME,
  second precision) — a sub-second --at records idempotently.
- bd provenance record|log|by-ref; logic shared in issueops, both Dolt
  stores delegate (mirrors the events pattern). The record command calls the
  exported ValidateProvenanceEvent for early CLI feedback, with the store as
  the real boundary.
- ADR-0003 records the rationale (why not extend events, why opaque ids,
  event-level append-only vs issue-bound cascade, distributed-merge note).
  CGO tests cover round trip, idempotency, sub-second-at idempotency, opaque
  field round-trip, and the validation guards.

* Fix provenance CLI lint and review nits

Return JSON output errors from provenance commands, silence Cobra usage/error duplication on the new command group, document deterministic provenance IDs accurately, and add the composite issue/occurred_at index promised by the design.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

* fix-merge(provenance): renumber to 0063, drop pinned-doc artifacts, stage provenance_events, ADR to engdocs

Maintainer-side rebase tail for PR 4461 after 505 commits of drift; author's
blockers were all fixed on 2026-07-08.

Co-authored-by: sjarmak <sjarmak@users.noreply.github.com>
Agent-Signature: claude-code-sonnet-builder on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix-merge(provenance) round 2: backend contract aliases + latest-migration mock shape

Two more surfaces main grew after the 7/27 approval:
- backend public-contract completeness ratchet (#5321) requires aliases
  for types reachable from the contract: add ProvKind + ProvenanceEvent
- schema lock tests script sqlmock against the LATEST migration's body
  shape; latest is now 0063 (plain CREATE TABLE -> ExecContext), not
  0062's bare CALL (-> DrainCall/QueryContext)

---------

Co-authored-by: sjarmak <sjarmak@users.noreply.github.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-07 09:43:20 -07:00

185 lines
6.3 KiB
Go

package backend
import (
"github.com/steveyegge/beads/internal/types"
)
// Domain types reached by the engine interface's method signatures, aliased
// from the internal domain package. Request/response types from the guarded
// issue-operations surface (issueops.Lifecycle, issueops.Reader) are already
// public in github.com/steveyegge/beads/issueops and are not re-exported
// here.
type (
BlockedIssue = types.BlockedIssue
BondRef = types.BondRef
Comment = types.Comment
CompactionCandidate = types.CompactionCandidate
CustomStatus = types.CustomStatus
DeleteIssuesResult = types.DeleteIssuesResult
Dependency = types.Dependency
DependencyCounts = types.DependencyCounts
DependencyType = types.DependencyType
EpicStatus = types.EpicStatus
Event = types.Event
EventType = types.EventType
Issue = types.Issue
IssueDetails = types.IssueDetails
IssueFilter = types.IssueFilter
IssueSnapshot = types.IssueSnapshot
IssueType = types.IssueType
IssueWithCounts = types.IssueWithCounts
IssueWithDependencyMetadata = types.IssueWithDependencyMetadata
Label = types.Label
MolType = types.MolType
MoleculeLastActivity = types.MoleculeLastActivity
MoleculeProgressStats = types.MoleculeProgressStats
PersistenceMode = types.PersistenceMode
ProvKind = types.ProvKind
ProvenanceEvent = types.ProvenanceEvent
ReclaimFilter = types.ReclaimFilter
ReclaimedLease = types.ReclaimedLease
SortPolicy = types.SortPolicy
StaleFilter = types.StaleFilter
Statistics = types.Statistics
Status = types.Status
StatusCategory = types.StatusCategory
StorageClass = types.StorageClass
TreeNode = types.TreeNode
WispFilter = types.WispFilter
WispType = types.WispType
WorkFilter = types.WorkFilter
WorkType = types.WorkType
)
// Status values.
const (
StatusOpen = types.StatusOpen
StatusInProgress = types.StatusInProgress
StatusBlocked = types.StatusBlocked
StatusDeferred = types.StatusDeferred
StatusClosed = types.StatusClosed
StatusHooked = types.StatusHooked
StatusPinned = types.StatusPinned
)
// IssueType values.
const (
TypeBug = types.TypeBug
TypeChore = types.TypeChore
TypeDecision = types.TypeDecision
TypeEpic = types.TypeEpic
TypeEvent = types.TypeEvent
TypeFeature = types.TypeFeature
TypeGate = types.TypeGate
TypeMessage = types.TypeMessage
TypeMilestone = types.TypeMilestone
TypeMolecule = types.TypeMolecule
TypeSpike = types.TypeSpike
TypeStory = types.TypeStory
TypeTask = types.TypeTask
)
// DependencyType values.
const (
DepApprovedBy = types.DepApprovedBy
DepAssignedTo = types.DepAssignedTo
DepAttests = types.DepAttests
DepAuthoredBy = types.DepAuthoredBy
DepBlocks = types.DepBlocks
DepCausedBy = types.DepCausedBy
DepConditionalBlocks = types.DepConditionalBlocks
DepDelegatedFrom = types.DepDelegatedFrom
DepDiscoveredFrom = types.DepDiscoveredFrom
DepDuplicates = types.DepDuplicates
DepParentChild = types.DepParentChild
DepRelated = types.DepRelated
DepRelatesTo = types.DepRelatesTo
DepRepliesTo = types.DepRepliesTo
DepSupersedes = types.DepSupersedes
DepTracks = types.DepTracks
DepUntil = types.DepUntil
DepValidates = types.DepValidates
DepWaitsFor = types.DepWaitsFor
)
// EventType values.
const (
EventCreated = types.EventCreated
EventUpdated = types.EventUpdated
EventClaimed = types.EventClaimed
EventStatusChanged = types.EventStatusChanged
EventCommented = types.EventCommented
EventClosed = types.EventClosed
EventReopened = types.EventReopened
EventDependencyAdded = types.EventDependencyAdded
EventDependencyRemoved = types.EventDependencyRemoved
EventLabelAdded = types.EventLabelAdded
EventLabelRemoved = types.EventLabelRemoved
EventLeaseReclaimed = types.EventLeaseReclaimed
EventCompacted = types.EventCompacted
)
// SortPolicy values.
const (
SortPolicyHybrid = types.SortPolicyHybrid
SortPolicyPriority = types.SortPolicyPriority
SortPolicyOldest = types.SortPolicyOldest
)
// StatusCategory values.
const (
CategoryUnspecified = types.CategoryUnspecified
CategoryActive = types.CategoryActive
CategoryWIP = types.CategoryWIP
CategoryFrozen = types.CategoryFrozen
CategoryDone = types.CategoryDone
)
// StorageClass values.
const (
StorageClassVersioned = types.StorageClassVersioned
StorageClassUnversioned = types.StorageClassUnversioned
StorageClassEphemeral = types.StorageClassEphemeral
)
// WispType values.
const (
WispTypeHeartbeat = types.WispTypeHeartbeat
WispTypePing = types.WispTypePing
WispTypePatrol = types.WispTypePatrol
WispTypeGCReport = types.WispTypeGCReport
WispTypeRecovery = types.WispTypeRecovery
WispTypeError = types.WispTypeError
WispTypeEscalation = types.WispTypeEscalation
)
// PersistenceMode values.
const (
PersistenceModePersistent = types.PersistenceModePersistent
PersistenceModeEphemeral = types.PersistenceModeEphemeral
PersistenceModeNoHistory = types.PersistenceModeNoHistory
)
// MolType values.
const (
MolTypeWork = types.MolTypeWork
MolTypeSwarm = types.MolTypeSwarm
MolTypePatrol = types.MolTypePatrol
)
// WorkType values.
const (
WorkTypeMutex = types.WorkTypeMutex
WorkTypeOpenCompetition = types.WorkTypeOpenCompetition
)
// MaxFieldLen is the maximum length (in characters) of the assignee, owner,
// and label fields; violations pair with ErrFieldTooLong.
const MaxFieldLen = types.MaxFieldLen
// Enumerations of the built-in values, in canonical order.
var (
AllStatuses = types.AllStatuses
AllIssueTypes = types.AllIssueTypes
AllDependencyTypes = types.AllDependencyTypes
)