* 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>
209 lines
6.5 KiB
Go
209 lines
6.5 KiB
Go
// Package main implements the bd CLI provenance event-log commands.
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
"time"
|
|
|
|
"github.com/spf13/cobra"
|
|
"github.com/steveyegge/beads/internal/storage/issueops"
|
|
"github.com/steveyegge/beads/internal/types"
|
|
"github.com/steveyegge/beads/internal/ui"
|
|
"github.com/steveyegge/beads/internal/utils"
|
|
)
|
|
|
|
var provenanceCmd = &cobra.Command{
|
|
Use: "provenance",
|
|
GroupID: "issues",
|
|
Short: "Append-only provenance event log",
|
|
SilenceUsage: true,
|
|
SilenceErrors: true,
|
|
Long: `Record and read provenance events: typed bindings from an issue to an
|
|
opaque external artifact (a git SHA, PR, work-id, transcript, or branch).
|
|
|
|
The log is append-only — there is no update or delete. bd never interprets the
|
|
actor or ref; only kind and ref-kind are structurally validated. Recording is
|
|
idempotent on a deterministic id, so a producer firing twice is harmless.`,
|
|
}
|
|
|
|
var (
|
|
provIssue string
|
|
provKind string
|
|
provSource string
|
|
provActor string
|
|
provRef string
|
|
provRefKind string
|
|
provAt string
|
|
provPayload string
|
|
// provLogKind backs `provenance log --kind`; kept separate from provKind
|
|
// (which backs `record --kind`) so the two flags cannot race a shared
|
|
// package var across command runs.
|
|
provLogKind string
|
|
)
|
|
|
|
var provenanceRecordCmd = &cobra.Command{
|
|
Use: "record --issue <id> --kind <k> --source <s>",
|
|
Short: "Record a provenance event (idempotent)",
|
|
SilenceUsage: true,
|
|
SilenceErrors: true,
|
|
Long: `Record a provenance event. The event is appended idempotently: a
|
|
deterministic id is computed from source:issue:kind:(ref or --at), so re-running
|
|
the same record is a no-op.
|
|
|
|
An event recorded without --ref requires --at so the id is caller-owned.`,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
CheckReadonly("provenance record")
|
|
ctx := rootCtx
|
|
|
|
issueID, err := utils.ResolvePartialID(ctx, store, provIssue)
|
|
if err != nil {
|
|
return HandleErrorRespectJSON("resolving %s: %v", provIssue, err)
|
|
}
|
|
|
|
ev := types.ProvenanceEvent{
|
|
IssueID: issueID,
|
|
Kind: types.ProvKind(provKind),
|
|
Source: provSource,
|
|
}
|
|
if provActor != "" {
|
|
ev.Actor = &provActor
|
|
}
|
|
if provRef != "" {
|
|
ev.Ref = &provRef
|
|
}
|
|
if provRefKind != "" {
|
|
ev.RefKind = &provRefKind
|
|
}
|
|
if provPayload != "" {
|
|
ev.Payload = &provPayload
|
|
}
|
|
if provAt != "" {
|
|
at, err := time.Parse(time.RFC3339, provAt)
|
|
if err != nil {
|
|
return HandleErrorRespectJSON("--at must be an RFC3339 timestamp (e.g. 2026-06-19T12:00:00Z): %v", err)
|
|
}
|
|
atUTC := at.UTC()
|
|
ev.OccurredAt = &atUTC
|
|
}
|
|
|
|
// Fail early with the same structural rules the store enforces, so the CLI
|
|
// gives friendly feedback before opening a transaction.
|
|
if err := issueops.ValidateProvenanceEvent(ev); err != nil {
|
|
return HandleErrorRespectJSON("%v", err)
|
|
}
|
|
|
|
id, inserted, err := store.RecordProvenanceEvent(ctx, ev)
|
|
if err != nil {
|
|
return HandleErrorRespectJSON("%v", err)
|
|
}
|
|
if inserted {
|
|
commandDidWrite.Store(true)
|
|
}
|
|
|
|
if jsonOutput {
|
|
return outputJSON(map[string]interface{}{
|
|
"id": id,
|
|
"inserted": inserted,
|
|
"issue_id": issueID,
|
|
"kind": provKind,
|
|
})
|
|
}
|
|
if inserted {
|
|
fmt.Printf("%s Recorded %s provenance %s on %s\n", ui.RenderPass("✓"), provKind, id, issueID)
|
|
} else {
|
|
fmt.Printf("%s Provenance %s already recorded (id %s)\n", ui.RenderAccent("•"), provKind, id)
|
|
}
|
|
return nil
|
|
},
|
|
}
|
|
|
|
var provenanceLogCmd = &cobra.Command{
|
|
Use: "log <issue-id>",
|
|
Short: "List provenance events for an issue",
|
|
Args: cobra.ExactArgs(1),
|
|
SilenceUsage: true,
|
|
SilenceErrors: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
ctx := rootCtx
|
|
issueID, err := utils.ResolvePartialID(ctx, store, args[0])
|
|
if err != nil {
|
|
return HandleErrorRespectJSON("resolving %s: %v", args[0], err)
|
|
}
|
|
events, err := store.GetProvenanceEvents(ctx, issueID, provLogKind)
|
|
if err != nil {
|
|
return HandleErrorRespectJSON("%v", err)
|
|
}
|
|
return outputProvenanceEvents(events)
|
|
},
|
|
}
|
|
|
|
var provenanceByRefCmd = &cobra.Command{
|
|
Use: "by-ref <ref>",
|
|
Short: "List provenance events bound to a ref",
|
|
Args: cobra.ExactArgs(1),
|
|
SilenceUsage: true,
|
|
SilenceErrors: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
ctx := rootCtx
|
|
events, err := store.GetProvenanceByRef(ctx, args[0])
|
|
if err != nil {
|
|
return HandleErrorRespectJSON("%v", err)
|
|
}
|
|
return outputProvenanceEvents(events)
|
|
},
|
|
}
|
|
|
|
func outputProvenanceEvents(events []types.ProvenanceEvent) error {
|
|
if jsonOutput {
|
|
if events == nil {
|
|
events = []types.ProvenanceEvent{}
|
|
}
|
|
return outputJSON(events)
|
|
}
|
|
if len(events) == 0 {
|
|
fmt.Println("No provenance events")
|
|
return nil
|
|
}
|
|
for _, ev := range events {
|
|
when := "—"
|
|
if ev.OccurredAt != nil {
|
|
when = ev.OccurredAt.Format(time.RFC3339)
|
|
}
|
|
line := fmt.Sprintf("%s %-8s %s", when, ev.Kind, ev.IssueID)
|
|
if ev.Ref != nil {
|
|
refKind := ""
|
|
if ev.RefKind != nil {
|
|
refKind = *ev.RefKind + ":"
|
|
}
|
|
line += fmt.Sprintf(" %s%s", refKind, *ev.Ref)
|
|
}
|
|
if ev.Actor != nil {
|
|
line += fmt.Sprintf(" by %s", *ev.Actor)
|
|
}
|
|
line += fmt.Sprintf(" (%s)", ev.Source)
|
|
fmt.Println(line)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func init() {
|
|
provenanceRecordCmd.Flags().StringVar(&provIssue, "issue", "", "issue id (required)")
|
|
provenanceRecordCmd.Flags().StringVar(&provKind, "kind", "", "event kind: cut|claim|suspend|resume|handoff|commit|land|used (required)")
|
|
provenanceRecordCmd.Flags().StringVar(&provSource, "source", "", "producer of the event, e.g. git-hook, orchestrator (required)")
|
|
provenanceRecordCmd.Flags().StringVar(&provActor, "actor", "", "opaque actor identifier (optional)")
|
|
provenanceRecordCmd.Flags().StringVar(&provRef, "ref", "", "opaque external reference, e.g. a SHA or PR url (optional)")
|
|
provenanceRecordCmd.Flags().StringVar(&provRefKind, "ref-kind", "", "ref kind: git-sha|pr|work-id|transcript|branch (optional)")
|
|
provenanceRecordCmd.Flags().StringVar(&provAt, "at", "", "event-time as RFC3339 (required for ref-less kinds)")
|
|
provenanceRecordCmd.Flags().StringVar(&provPayload, "payload", "", "opaque payload, e.g. JSON (optional)")
|
|
_ = provenanceRecordCmd.MarkFlagRequired("issue")
|
|
_ = provenanceRecordCmd.MarkFlagRequired("kind")
|
|
_ = provenanceRecordCmd.MarkFlagRequired("source")
|
|
|
|
provenanceLogCmd.Flags().StringVar(&provLogKind, "kind", "", "filter by kind (optional)")
|
|
provenanceLogCmd.ValidArgsFunction = issueIDCompletion
|
|
|
|
provenanceCmd.AddCommand(provenanceRecordCmd)
|
|
provenanceCmd.AddCommand(provenanceLogCmd)
|
|
provenanceCmd.AddCommand(provenanceByRefCmd)
|
|
rootCmd.AddCommand(provenanceCmd)
|
|
}
|