Unify enrichment tracking and outcome-based status

Make common_tracker_patterns and common_third_parties share one
enrichment-tracking model and fix the misleading proboctl status.

Both tables now carry the enrichment JSONB provenance payload, an
enrichment_attempts counter, and a last_enrichment_attempt_at clock.
On common_tracker_patterns the enriched_at done-flag is renamed to
last_enrichment_attempt_at and stamped at claim time, so it is truthful
to "attempt" rather than "success". A row is considered to have been
through the workflow when it carries an enrichment payload, not when a
timestamp is set, which lets stale recovery key off the payload being
absent with budget remaining, exactly like common_third_parties.

The claim path reads the attempt counter and timestamp back via
RETURNING so the in-memory receiver matches the database clock instead
of a separate app-side time.Now.

The enricher builds a per-field provenance payload (description and
third-party outcomes plus the mapping attribution) and persists it via
UpdateEnrichment, named to mirror the common-third-party sibling. The
common pattern enrichment worker gains a max-attempts ceiling so a
permanently failing row stops looping.

proboctl now shows "enriched" only when every field the last run
recorded an outcome for resolved a value, otherwise "partial (X/Y)",
replacing the misleading "enriched (no description)" label.

Signed-off-by: Émile Ré <emile@probo.com>

pkg/proboctl/commonthirdparty/commonthirdparty.go

@@ -48,19 +48,63 @@ func NewCmdCommonThirdParty(f *cmdutil.Factory) *cobra.Command {
 }
 
 // enrichmentState classifies a common third party's position in the
-// enrichment lifecycle for display. A row is "enriched" once it carries
-// an enrichment payload; there is no enriched_at column.
+// enrichment lifecycle for display. A row that has been through the
+// workflow (it carries an enrichment payload) reads "enriched" only when
+// every field the last run recorded an outcome for resolved a value;
+// otherwise it reads "partial (X/Y)".
 func enrichmentState(p *coredata.CommonThirdParty) string {
 	switch {
 	case p.EnrichmentRequestedAt != nil:
 		return "queued"
 	case len(p.Enrichment) > 0:
-		return "enriched"
+		resolved, total := enrichmentCompleteness(p)
+		if total == 0 || resolved == total {
+			return "enriched"
+		}
+
+		return fmt.Sprintf("partial (%d/%d)", resolved, total)
 	default:
 		return "unenriched"
 	}
 }
 
+// resolvedFieldStatuses are the per-field enrichment statuses that carry a
+// value, as opposed to not_found / low_confidence.
+var resolvedFieldStatuses = map[string]struct{}{
+	"found":                 {},
+	"exists_external":       {},
+	"fallback_display_name": {},
+}
+
+// enrichmentCompleteness counts how many of the fields the last enrichment
+// run recorded an outcome for resolved a value (X) versus the total it
+// recorded (Y), parsed from the enrichment payload's per-field provenance.
+func enrichmentCompleteness(p *coredata.CommonThirdParty) (resolved, total int) {
+	if len(p.Enrichment) == 0 {
+		return 0, 0
+	}
+
+	var meta struct {
+		Fields map[string]struct {
+			Status string `json:"status"`
+		} `json:"fields"`
+	}
+
+	if err := json.Unmarshal(p.Enrichment, &meta); err != nil {
+		return 0, 0
+	}
+
+	for _, f := range meta.Fields {
+		total++
+
+		if _, ok := resolvedFieldStatuses[f.Status]; ok {
+			resolved++
+		}
+	}
+
+	return resolved, total
+}
+
 // enrichmentStatus returns the run-level status recorded in the
 // enrichment payload (done, partial, failed), or an empty string when
 // the row has never been enriched or the payload is malformed.

pkg/proboctl/commonthirdparty/show.go

@@ -147,6 +147,10 @@ func newCmdShow(f *cmdutil.Factory) *cobra.Command {
 		row("Enrichment state:", enrichmentState(&party))
 		row("Enrichment attempts:", fmt.Sprintf("%d", party.EnrichmentAttempts))
 
+		if party.LastEnrichmentAttemptAt != nil {
+			row("Last attempt:", party.LastEnrichmentAttemptAt.Format("2006-01-02 15:04:05"))
+		}
+
 		if party.EnrichmentRequestedAt != nil {
 			row("Queued at:", party.EnrichmentRequestedAt.Format("2006-01-02 15:04:05"))
 		}
@@ -180,7 +184,7 @@ func printEnrichmentDetails(out io.Writer, label lipgloss.Style, party coredata.
 	}
 
 	if !meta.AttemptedAt.IsZero() {
-		row("Last attempt:", meta.AttemptedAt.Format("2006-01-02 15:04:05"))
+		row("Last run recorded:", meta.AttemptedAt.Format("2006-01-02 15:04:05"))
 	}
 
 	if meta.Model != "" {

pkg/proboctl/commontrackerpattern/commontrackerpattern.go

@@ -16,6 +16,7 @@ package commontrackerpattern
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 
@@ -47,20 +48,62 @@ func NewCmdCommonTrackerPattern(f *cmdutil.Factory) *cobra.Command {
 }
 
 // enrichmentState classifies a pattern's position in the enrichment
-// lifecycle for display.
+// lifecycle for display. A row that has been through the workflow (it
+// carries an enrichment payload) reads "enriched" only when every field
+// the last run recorded an outcome for resolved a value; otherwise it
+// reads "partial (X/Y)".
 func enrichmentState(p *coredata.CommonTrackerPattern) string {
 	switch {
 	case p.EnrichmentRequestedAt != nil:
 		return "queued"
-	case p.EnrichedAt != nil && p.Description == "":
-		return "enriched (no description)"
-	case p.EnrichedAt != nil:
-		return "enriched"
+	case len(p.Enrichment) > 0:
+		resolved, total := enrichmentCompleteness(p)
+		if total == 0 || resolved == total {
+			return "enriched"
+		}
+
+		return fmt.Sprintf("partial (%d/%d)", resolved, total)
 	default:
 		return "unenriched"
 	}
 }
 
+// resolvedFieldStatuses are the per-field enrichment statuses that carry a
+// value, as opposed to not_found.
+var resolvedFieldStatuses = map[string]struct{}{
+	"found":           {},
+	"exists_external": {},
+}
+
+// enrichmentCompleteness counts how many of the fields the last enrichment
+// run recorded an outcome for resolved a value (X) versus the total it
+// recorded (Y), parsed from the enrichment payload's per-field provenance.
+func enrichmentCompleteness(p *coredata.CommonTrackerPattern) (resolved, total int) {
+	if len(p.Enrichment) == 0 {
+		return 0, 0
+	}
+
+	var meta struct {
+		Fields map[string]struct {
+			Status string `json:"status"`
+		} `json:"fields"`
+	}
+
+	if err := json.Unmarshal(p.Enrichment, &meta); err != nil {
+		return 0, 0
+	}
+
+	for _, f := range meta.Fields {
+		total++
+
+		if _, ok := resolvedFieldStatuses[f.Status]; ok {
+			resolved++
+		}
+	}
+
+	return resolved, total
+}
+
 // resolveCommonThirdPartyID accepts either a common third party GID or a
 // slug and returns the corresponding id.
 func resolveCommonThirdPartyID(ctx context.Context, conn pg.Querier, value string) (gid.GID, error) {

pkg/proboctl/commontrackerpattern/list.go

@@ -59,7 +59,7 @@ func newCmdList(f *cmdutil.Factory) *cobra.Command {
 	cmd.Flags().StringVar(&flagState, "state", "", "Filter by enrichment state (queued, enriched, unenriched)")
 	cmd.Flags().BoolVar(&flagWithCommonThirdParty, "with-common-third-party", false, "Filter by whether the pattern is linked to a common third party (true/false); ignored when not set")
 	cmd.Flags().BoolVar(&flagWithoutDescription, "without-description", false, "Only patterns with a blank description")
-	cmd.Flags().StringVar(&flagSort, "sort", "confidence", "Sort field: pattern, confidence, created, updated, enriched")
+	cmd.Flags().StringVar(&flagSort, "sort", "confidence", "Sort field: pattern, confidence, created, updated, attempted")
 	cmd.Flags().StringVar(&flagOrder, "order", "", "Sort order: asc, desc (default depends on field)")
 
 	pageFlags := cmdutil.AddPageFlags(cmd)
@@ -277,10 +277,10 @@ func parseOrderBy(sort, order string) (page.OrderBy[coredata.CommonTrackerPatter
 		field, defaultDesc = coredata.CommonTrackerPatternOrderFieldCreatedAt, true
 	case "updated":
 		field, defaultDesc = coredata.CommonTrackerPatternOrderFieldUpdatedAt, true
-	case "enriched":
-		field, defaultDesc = coredata.CommonTrackerPatternOrderFieldEnrichedAt, true
+	case "attempted":
+		field, defaultDesc = coredata.CommonTrackerPatternOrderFieldLastEnrichmentAttemptAt, true
 	default:
-		return zeroOrderBy, fmt.Errorf("invalid --sort value %q: valid values are pattern, confidence, created, updated, enriched", sort)
+		return zeroOrderBy, fmt.Errorf("invalid --sort value %q: valid values are pattern, confidence, created, updated, attempted", sort)
 	}
 
 	direction := page.OrderDirectionAsc

pkg/proboctl/commontrackerpattern/set_description.go

@@ -16,8 +16,10 @@ package commontrackerpattern
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"time"
 
 	"github.com/spf13/cobra"
 	"go.gearno.de/kit/pg"
@@ -26,6 +28,41 @@ import (
 	"go.probo.inc/probo/pkg/proboctl/cmdutil"
 )
 
+// manualEnrichmentPayload builds the enrichment provenance written when an
+// operator sets a description by hand. It records only the description
+// outcome (resolved), so the row reads "enriched" and the enrichment
+// worker leaves it alone, while marking the source as manual for audit.
+func manualEnrichmentPayload() json.RawMessage {
+	now := time.Now()
+
+	payload := struct {
+		Status      string    `json:"status"`
+		Source      string    `json:"source"`
+		AttemptedAt time.Time `json:"attempted_at"`
+		Fields      map[string]struct {
+			Status    string    `json:"status"`
+			UpdatedAt time.Time `json:"updated_at"`
+		} `json:"fields"`
+	}{
+		Status:      "manual",
+		Source:      "manual",
+		AttemptedAt: now,
+		Fields: map[string]struct {
+			Status    string    `json:"status"`
+			UpdatedAt time.Time `json:"updated_at"`
+		}{
+			"description": {Status: "found", UpdatedAt: now},
+		},
+	}
+
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return nil
+	}
+
+	return raw
+}
+
 func newCmdSetDescription(f *cmdutil.Factory) *cobra.Command {
 	var (
 		flagDescription string
@@ -83,7 +120,7 @@ func newCmdSetDescription(f *cmdutil.Factory) *cobra.Command {
 					return fmt.Errorf("cannot load common tracker pattern: %w", err)
 				}
 
-				if err := pattern.SetEnriched(ctx, tx, flagDescription, nil); err != nil {
+				if err := pattern.UpdateEnrichment(ctx, tx, flagDescription, nil, manualEnrichmentPayload()); err != nil {
 					return fmt.Errorf("cannot set common tracker pattern description: %w", err)
 				}
 

pkg/proboctl/commontrackerpattern/show.go

@@ -127,12 +127,14 @@ func renderPatternDetail(f *cmdutil.Factory, p coredata.CommonTrackerPattern, th
 
 	row("Description:", description)
 
+	row("Enrichment attempts:", fmt.Sprintf("%d", p.EnrichmentAttempts))
+
 	if p.EnrichmentRequestedAt != nil {
 		row("Enrichment queued:", p.EnrichmentRequestedAt.Format("2006-01-02 15:04:05"))
 	}
 
-	if p.EnrichedAt != nil {
-		row("Enriched at:", p.EnrichedAt.Format("2006-01-02 15:04:05"))
+	if p.LastEnrichmentAttemptAt != nil {
+		row("Last attempt:", p.LastEnrichmentAttemptAt.Format("2006-01-02 15:04:05"))
 	}
 
 	row("Created:", p.CreatedAt.Format("2006-01-02 15:04:05"))