docs(parser): clarify provider facade invariants

The provider facade contract has to be understandable from the Go package itself because future provider migrations will implement against these types, not just the design document. Ambiguous parse error boundaries or source identity fields would let providers diverge in skip-cache, retry, and persisted lookup behavior even if they compile against the same interface.

This keeps the runtime surface unchanged while making whole-source errors, partial multi-session outcomes, persisted source identity, and capability/default-method expectations explicit at the interface layer.

Author: mariusvniekerk

internal/parser/capabilities.go

@@ -13,6 +13,11 @@ const (
 )
 
 // Capabilities groups provider source mechanics and parsed-content features.
+// Capabilities are declarative: a concrete provider that reports Supported must
+// implement the matching behavior rather than relying on ProviderBase defaults.
+// Callers may still invoke optional methods and handle their no-op or typed
+// unsupported results, but scheduling and validation should trust this
+// declaration once a provider has migrated off the legacy adapter.
 type Capabilities struct {
 	Source  SourceCapabilities
 	Content ContentCapabilities

internal/parser/provider.go

@@ -71,6 +71,11 @@ type Provider interface {
 	FindSource(context.Context, FindSourceRequest) (SourceRef, bool, error)
 	Fingerprint(context.Context, SourceRef) (SourceFingerprint, error)
 
+	// Parse returns a normalized outcome for one logical source. A non-nil
+	// error is a whole-source failure, including context cancellation; callers
+	// must ignore the returned ParseOutcome. Partial multi-session success is
+	// represented by a nil error with successful Results plus SourceErrors for
+	// isolated per-session failures.
 	Parse(context.Context, ParseRequest) (ParseOutcome, error)
 	ParseIncremental(
 		context.Context,
@@ -139,12 +144,24 @@ func (b ProviderBase) unsupported(feature string) error {
 
 // SourceRef is the engine-visible handle for provider-owned source data.
 type SourceRef struct {
-	Provider       AgentType
-	Key            string
-	DisplayPath    string
+	// Provider identifies the provider that created this source and must match
+	// the provider instance used for subsequent operations.
+	Provider AgentType
+	// Key is stable within the provider across process restarts. It is suitable
+	// for dedupe and diagnostics, but not necessarily for DB freshness checks.
+	Key string
+	// DisplayPath is human-readable and may be a virtual path.
+	DisplayPath string
+	// FingerprintKey is the persisted lookup key for skip-cache and parser data
+	// version checks. Migrated providers should keep it compatible with legacy
+	// file_path values whenever practical.
 	FingerprintKey string
-	ProjectHint    string
-	Opaque         any
+	// ProjectHint is advisory metadata for UI grouping and may be empty.
+	ProjectHint string
+	// Opaque is provider-owned in-memory state. The engine must not persist,
+	// compare, inspect, or log it, and providers must not require it for lookup
+	// from persisted rows.
+	Opaque any
 }
 
 // WatchPlan describes provider-owned filesystem watch roots.
@@ -196,7 +213,8 @@ type ParseRequest struct {
 	ForceParse  bool
 }
 
-// ParseOutcome is the full-parse provider output.
+// ParseOutcome is the full-parse provider output. It is meaningful only when
+// Provider.Parse returns a nil error.
 type ParseOutcome struct {
 	Results            []ParseResultOutcome
 	ExcludedSessionIDs []string
@@ -215,6 +233,8 @@ type ParseResultOutcome struct {
 }
 
 // SourceError reports a per-session parse failure from a multi-session source.
+// Providers use the Parse error return instead when a failure cannot be
+// isolated to a persisted full session ID.
 type SourceError struct {
 	SourceKey   string
 	DisplayPath string

internal/parser/provider_test.go

@@ -148,6 +148,64 @@ func TestProviderRegistryMirrorsAgentRegistry(t *testing.T) {
 	}
 }
 
+func TestLegacyProviderCapabilitiesMatchBaseDefaults(t *testing.T) {
+	provider, ok := NewProvider(AgentCodex, ProviderConfig{
+		Roots:   []string{t.TempDir()},
+		Machine: "devbox",
+	})
+	require.True(t, ok)
+	require.NotNil(t, provider)
+
+	assert.Equal(t, Capabilities{}, provider.Capabilities())
+
+	ctx := context.Background()
+	discovered, err := provider.Discover(ctx)
+	require.NoError(t, err)
+	assert.Empty(t, discovered)
+
+	plan, err := provider.WatchPlan(ctx)
+	require.NoError(t, err)
+	assert.Empty(t, plan.Roots)
+
+	changed, err := provider.SourcesForChangedPath(ctx, ChangedPathRequest{
+		Path:      "/tmp/session.jsonl",
+		EventKind: "write",
+		WatchRoot: "/tmp",
+	})
+	require.NoError(t, err)
+	assert.Empty(t, changed)
+
+	source, found, err := provider.FindSource(ctx, FindSourceRequest{
+		RawSessionID:   "session",
+		FullSessionID:  "codex:session",
+		StoredFilePath: "/tmp/session.jsonl",
+		FingerprintKey: "/tmp/session.jsonl",
+	})
+	require.NoError(t, err)
+	assert.False(t, found)
+	assert.Empty(t, source)
+
+	_, err = provider.Fingerprint(ctx, SourceRef{
+		Provider:       AgentCodex,
+		Key:            "session",
+		DisplayPath:    "/tmp/session.jsonl",
+		FingerprintKey: "/tmp/session.jsonl",
+	})
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, ErrUnsupportedProviderFeature))
+
+	incremental, status, err := provider.ParseIncremental(ctx, IncrementalRequest{
+		Source:       SourceRef{Provider: AgentCodex, Key: "session"},
+		Fingerprint:  SourceFingerprint{Key: "/tmp/session.jsonl"},
+		SessionID:    "codex:session",
+		StartOrdinal: 1,
+		Machine:      "devbox",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, IncrementalUnsupported, status)
+	assert.Empty(t, incremental)
+}
+
 func TestProviderFactoryLookupAndConfigSnapshot(t *testing.T) {
 	cfg := ProviderConfig{
 		Roots:   []string{"/tmp/one", "/tmp/two"},