Split Intent metadata off ImportConfigAdapter into IntentAdapter.

Stops JSON/XML from stubbing Orphan/SensitivePaths; Intent Get/GetAll
return IntentAdapter while Running stays ImportConfigAdapter.

Author: steiler

mocks/mockcacheclient/client.go

@@ -20,9 +20,39 @@ family (own accessors, own storage, excluded from `InstanceIntentGetAll`)
 under every backend, because it was never config-server's data to begin with.
 _Avoid_: calling it an intent, "the running intent" as a `Client`-level type.
 
+**Orphan**:
+Deletion policy for an Intent: drop it from the intended store (stop
+managing it) without deleting the corresponding config on the device,
+leaving that config unmanaged. Wire `Orphan`, internal `onlyIntended` /
+`DeleteOnlyIntended`, and config-server `DeletionPolicy=orphan` are the
+same bit. _Avoid_: a second meaning for leaf-variant "orphan delete"
+(same policy); "orphan" for unowned tree nodes or "Intent not found".
+
 **ImportConfigAdapter**:
-The mechanical, backend-agnostic shape `Client`'s read-side methods return:
-"data ready to hand to `Tree.ImportConfig`." Every `Client.*Get`/`*GetAll`
-method returns this shape — including `InstanceRunningGet` — regardless of
-whether the underlying value is an `Intent` or `Running`, and regardless of
-how many concrete representations exist behind it for a given backend.
+The mechanical shape ready to hand to `Tree.ImportConfig` (tree walk plus
+import-needed metadata: name, priority, deletes, non-revertive). Returned
+directly by Running reads (`InstanceRunningGet`). Intent reads return
+`IntentAdapter`, which embeds this shape. _Avoid_: putting Orphan or path
+markers on this interface; those are Intent-only (see **IntentAdapter**).
+
+**IntentAdapter**:
+The `Client` Intent-read shape: an `ImportConfigAdapter` plus Intent-only
+metadata (Orphan, path markers / SensitivePaths). Returned by
+`InstanceIntentGet` / `InstanceIntentGetAll`. Implemented by proto- and
+Document-backed adapters; never by JSON/XML device/running importers.
+_Avoid_: `IntentDescriptor` for this type; conflating with
+`IntentResponseAdapter` (northbound GetIntent response that also carries a
+Tree Entry).
+
+**ConfigSnapshotService**:
+The canonical local gRPC seam name for config-server-backed intent reads and
+writes (`Get`/`List`/`Modify`/`Delete`) against `TargetSnapshot` data. _Avoid_:
+using the older `ConfigReadService` name for current behavior.
+
+**Namespaced name**:
+Under `Cache.Type: config-server` only, the `namespace.name` spelling (split on
+the first `.`) used for a Target's datastore identity and for an Intent's
+owner / Config identity. The local backend has no namespaces and does not use
+this spelling. _Avoid_: treating this as a `Client`-level concept; "GVKNSN" as
+the everyday term (wire/comment echo of config-server); implying the local
+cache understands dotted names.

mocks/mockcacheclient/clientbound.go

@@ -25,9 +25,9 @@ import (
 // it's the one capability every Cache.Type genuinely has data for.
 type IntentReader interface {
 	InstanceIntentsList(ctx context.Context, cacheInstanceName string) ([]string, error)
-	InstanceIntentGet(ctx context.Context, cacheName string, intentName string) (importer.ImportConfigAdapter, error)
+	InstanceIntentGet(ctx context.Context, cacheName string, intentName string) (importer.IntentAdapter, error)
 	InstanceIntentExists(ctx context.Context, cacheName string, intentName string) (bool, error)
-	InstanceIntentGetAll(ctx context.Context, cacheName string, excludeIntentNames []string, intentChan chan<- importer.ImportConfigAdapter, errChan chan<- error)
+	InstanceIntentGetAll(ctx context.Context, cacheName string, excludeIntentNames []string, intentChan chan<- importer.IntentAdapter, errChan chan<- error)
 }
 
 // IntentWriter persists real Intents. Backends that don't own real-Intent

pkg/cache/CONTEXT.md

@@ -24,9 +24,9 @@ import (
 // BoundIntentReader is the bound-call equivalent of IntentReader.
 type BoundIntentReader interface {
 	IntentsList(ctx context.Context) ([]string, error)
-	IntentGet(ctx context.Context, intentName string) (importer.ImportConfigAdapter, error)
+	IntentGet(ctx context.Context, intentName string) (importer.IntentAdapter, error)
 	IntentExists(ctx context.Context, intentName string) (bool, error)
-	IntentGetAll(ctx context.Context, excludeIntentNames []string, intentChan chan<- importer.ImportConfigAdapter, errChan chan<- error)
+	IntentGetAll(ctx context.Context, excludeIntentNames []string, intentChan chan<- importer.IntentAdapter, errChan chan<- error)
 }
 
 // BoundIntentWriter is the bound-call equivalent of IntentWriter.
@@ -83,7 +83,7 @@ func (c *CacheClientBoundImpl) InstanceExists(ctx context.Context) bool {
 func (c *CacheClientBoundImpl) IntentsList(ctx context.Context) ([]string, error) {
 	return c.cacheClient.InstanceIntentsList(ctx, c.cacheName)
 }
-func (c *CacheClientBoundImpl) IntentGet(ctx context.Context, intentName string) (importer.ImportConfigAdapter, error) {
+func (c *CacheClientBoundImpl) IntentGet(ctx context.Context, intentName string) (importer.IntentAdapter, error) {
 	return c.cacheClient.InstanceIntentGet(ctx, c.cacheName, intentName)
 }
 func (c *CacheClientBoundImpl) IntentModify(ctx context.Context, intent *tree_persist.Intent) error {
@@ -95,7 +95,7 @@ func (c *CacheClientBoundImpl) IntentDelete(ctx context.Context, intentName stri
 func (c *CacheClientBoundImpl) IntentExists(ctx context.Context, intentName string) (bool, error) {
 	return c.cacheClient.InstanceIntentExists(ctx, c.cacheName, intentName)
 }
-func (c *CacheClientBoundImpl) IntentGetAll(ctx context.Context, excludeIntentNames []string, intentChan chan<- importer.ImportConfigAdapter, errChan chan<- error) {
+func (c *CacheClientBoundImpl) IntentGetAll(ctx context.Context, excludeIntentNames []string, intentChan chan<- importer.IntentAdapter, errChan chan<- error) {
 	c.cacheClient.InstanceIntentGetAll(ctx, c.cacheName, excludeIntentNames, intentChan, errChan)
 }
 func (c *CacheClientBoundImpl) RunningGet(ctx context.Context) (importer.ImportConfigAdapter, error) {

pkg/cache/cache.go

@@ -0,0 +1,21 @@
+# Intent vs Running Client return-type split
+
+**Status:** accepted
+
+**Pairs with:** `.scratch/open/03-split-intent-metadata-off-import-adapter.md`
+
+`ImportConfigAdapter` grew `GetOrphan` / `GetSensitivePaths` so cache backends could surface Intent metadata through the same type used for tree walk. JSON/XML forever stubbed those accessors; the import processor never reads them. Every new Intent-only field would force another stub on device/running importers — classic shallow widening.
+
+**Decision:** narrow `ImportConfigAdapter` to tree walk plus import-needed metadata (name, priority, deletes, non-revertive). Introduce `IntentAdapter` (`ImportConfigAdapter` + `GetOrphan` / `GetSensitivePaths`) in `pkg/tree/importer`. Client Intent reads (`InstanceIntentGet` / `InstanceIntentGetAll`, and their bound equivalents) return `IntentAdapter`; Running reads (`InstanceRunningGet`) stay `ImportConfigAdapter`. `documentImporter` and `ProtoTreeImporter` implement `IntentAdapter`; JSON/XML do not.
+
+## Considered options
+
+- **Type-assert Orphan/SensitivePaths at Intent call sites.** Rejected: silent miss when a non-Intent adapter arrives; callers must remember to assert.
+- **Separate Client methods for Intent metadata.** Rejected: extra hop for every Intent Get; metadata belongs with the adapter already in hand.
+- **Keep a single return type; leave stubs on JSON/XML.** Rejected: fails the deletion test — every new Intent field forces another stub.
+- **Name `IntentDescriptor`.** Rejected: clashes with northbound response vocabulary; `IntentAdapter` mirrors `ImportConfigAdapter` and stays distinct from `IntentResponseAdapter`.
+- **House `IntentAdapter` under `pkg/cache`.** Rejected: would create a cache←tree reverse dependency or force a wrapper; it lives beside `ImportConfigAdapter` in `pkg/tree/importer`.
+
+## Consequences
+
+Intent-only metadata no longer pollutes device/running importers. `populateSensitivePathIndex` and GetIntent read Orphan/SensitivePaths through `IntentAdapter`. `configsnapshot.NewImportAdapter` returns `IntentAdapter`. Expanding GetIntentResponse / TransactionIntent / config-server wire is out of scope for this split.

pkg/cache/cacheClientBound.go

@@ -50,26 +50,27 @@ type LocalCache struct {
 }
 
 // decodeIntent unmarshals the disk-backed store's raw bytes into a
-// *tree_persist.Intent and wraps it as an importer.ImportConfigAdapter — the
+// *tree_persist.Intent and wraps it as an importer.IntentAdapter — the
 // shared decode step every InstanceIntentGet/InstanceIntentGetAll/
-// InstanceRunningGet call site needs.
-func (l *LocalCache) decodeIntent(b []byte) (importer.ImportConfigAdapter, error) {
+// InstanceRunningGet call site needs. Running callers narrow to
+// ImportConfigAdapter at the RunningStore boundary.
+func (l *LocalCache) decodeIntent(b []byte) (importer.IntentAdapter, error) {
 	result := &tree_persist.Intent{}
 	if err := proto.Unmarshal(b, result); err != nil {
 		return nil, err
 	}
 	return treeproto.NewProtoTreeImporter(result), nil
 }
 
-func (l *LocalCache) InstanceIntentGet(ctx context.Context, cacheName string, intentName string) (importer.ImportConfigAdapter, error) {
+func (l *LocalCache) InstanceIntentGet(ctx context.Context, cacheName string, intentName string) (importer.IntentAdapter, error) {
 	b, err := l.Cache.InstanceIntentGet(ctx, cacheName, intentName)
 	if err != nil {
 		return nil, err
 	}
 	return l.decodeIntent(b)
 }
 
-func (l *LocalCache) InstanceIntentGetAll(ctx context.Context, cacheName string, excludeIntentNames []string, intentChanOrig chan<- importer.ImportConfigAdapter, errChanOrig chan<- error) {
+func (l *LocalCache) InstanceIntentGetAll(ctx context.Context, cacheName string, excludeIntentNames []string, intentChanOrig chan<- importer.IntentAdapter, errChanOrig chan<- error) {
 	// create new channels
 	intentChan := make(chan *types.Intent, 5)
 	errChan := make(chan error, 1)

pkg/cache/docs/adr/0005-intent-vs-running-adapter-return-type.md

@@ -64,9 +64,9 @@ func TestLocalCache_InstanceIntentGetRoundTrip(t *testing.T) {
 // TestLocalCache_RunningRoundTrip verifies InstanceRunningModify/InstanceRunningGet
 // are thin passthroughs to the same disk-backed store InstanceIntentGet/Modify use,
 // so the local backend's on-disk behavior for "running" is unchanged by the split.
-// InstanceRunningGet returns an importer.ImportConfigAdapter — the same mechanical
-// "ready for Tree.ImportConfig" shape InstanceIntentGet returns — rather than the
-// raw *tree_persist.Intent, so the assertions go through its accessors.
+// InstanceRunningGet returns an importer.ImportConfigAdapter (Intent reads return
+// IntentAdapter) rather than the raw *tree_persist.Intent, so the assertions go
+// through its accessors.
 func TestLocalCache_RunningRoundTrip(t *testing.T) {
 	ctx := context.Background()
 	lc := newTestLocalCache(t)
@@ -129,7 +129,7 @@ func TestLocalCache_RunningExcludedFromIntentGetAll(t *testing.T) {
 		t.Fatalf("InstanceIntentModify: %v", err)
 	}
 
-	intentChan := make(chan importer.ImportConfigAdapter)
+	intentChan := make(chan importer.IntentAdapter)
 	errChan := make(chan error, 1)
 	go lc.InstanceIntentGetAll(ctx, cacheName, []string{consts.RunningIntentName}, intentChan, errChan)
 

pkg/cache/local.go

@@ -299,7 +299,7 @@ var _ types.RollbackInterface = &DatastoreRollbackAdapter{}
 // sensitive_paths into s. It is called once during Datastore startup, before
 // the first northbound read is served.
 func populateSensitivePathIndex(ctx context.Context, s *treetypes.SensitivePathIndex, cc cache.BoundIntentReader) error {
-	return forEachIntent(ctx, cc, []string{consts.RunningIntentName}, func(intent importer.ImportConfigAdapter) error {
+	return forEachIntent(ctx, cc, []string{consts.RunningIntentName}, func(intent importer.IntentAdapter) error {
 		if len(intent.GetSensitivePaths()) > 0 {
 			s.Set(intent.GetName(), intent.GetSensitivePaths())
 		}

pkg/cache/local_test.go

@@ -32,7 +32,7 @@ func TestPopulateSensitivePathIndex_NarrowIntentReader(t *testing.T) {
 	reader := mockcacheclient.NewMockBoundIntentReader(ctrl)
 	reader.EXPECT().
 		IntentGetAll(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).
-		DoAndReturn(func(_ context.Context, _ []string, intentChan chan<- importer.ImportConfigAdapter, errChan chan<- error) {
+		DoAndReturn(func(_ context.Context, _ []string, intentChan chan<- importer.IntentAdapter, errChan chan<- error) {
 			intentChan <- treeproto.NewProtoTreeImporter(withPaths)
 			intentChan <- treeproto.NewProtoTreeImporter(withoutPaths)
 			close(intentChan)