Make TagMap a facade over an id store and a name store

TagMap keeps known tags in an IdStore (by id) and custom tags in a
HashStore (by name), instead of one bucket array. A name is classified
once, at the boundary, and routed to its store; known and custom tags
never share a key, so read-through and precedence work per store and
never cross between them. The name store is created on the first custom
write; until then a map borrows its read-through parent's store
read-only.

Behavior is unchanged: the TagMap suites pass as they are, and Entry
objects are still shared across copies. The span still holds a single
TagMap; it starts owning the stores directly in the next change.
TagMap.Internals stays for now, writing straight to the id store, and
goes away with that change.

Reads by id go straight to the id store. stream() and spliterator()
yield stable Entries, and getEntryReader gives a momentary reader for
typed reads. TagStoresTest covers the stores through TagMap, and
IdStoreContractTest gains the view cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: dougqh

gradle/forbiddenApiFilters/instrumentation.txt

@@ -7,3 +7,14 @@ datadog.trace.bootstrap.instrumentation.api.AgentSpan#setServiceName(java.lang.S
 # (see datadog.apicontract.Restricted). Instrumentation uses TagMap's checked methods.
 @defaultMessage TagMap.internals() is restricted to the tracer core; use TagMap's checked methods instead.
 datadog.trace.api.TagMap#internals()
+
+# A span's tag stores, how it gets them from a parent, and the span's view of them skip checks the tracer
+# core has already made; they are @Restricted to the core (see datadog.apicontract.Restricted).
+# Instrumentation uses TagMap's checked methods.
+@defaultMessage Tag stores are restricted to the tracer core; use TagMap's checked methods instead.
+datadog.trace.api.HashStore
+datadog.trace.api.IdStore
+datadog.trace.api.TagMap#readThroughParent(datadog.trace.api.TagMap)
+datadog.trace.api.TagMap#viewOf(datadog.trace.api.IdStore,datadog.trace.api.HashStore,boolean)
+datadog.trace.api.TagMap#customStore()
+datadog.trace.api.TagMap#isCustomStoreBorrowed()

internal-api/src/main/java/datadog/trace/api/HashStore.java

@@ -38,6 +38,14 @@ public final class HashStore {
    */
   private Set<String> removedFromParent;
 
+  /**
+   * {@code parent}'s custom store, for an owner to borrow read-only until its first custom write,
+   * or null.
+   */
+  public static HashStore inheritedFrom(TagMap parent) {
+    return parent == null ? null : parent.nameStore;
+  }
+
   /**
    * A fresh custom store for an owner's first custom write, reading through to {@code borrowed},
    * the store it borrowed until now (may be null).

internal-api/src/main/java/datadog/trace/api/HashSupport.java

@@ -414,24 +414,6 @@ static String toInternalString(Object[] buckets) {
     return ledger.toString();
   }
 
-  /** Whether {@code buckets} holds no entry, checked bucket by bucket. */
-  static boolean isEmpty(Object[] buckets) {
-    Object[] thisBuckets = buckets;
-
-    for (int i = 0; i < thisBuckets.length; ++i) {
-      Object curBucket = thisBuckets[i];
-
-      if (curBucket instanceof Entry) {
-        return false;
-      } else if (curBucket instanceof BucketGroup) {
-        BucketGroup curGroup = (BucketGroup) curBucket;
-        if (!curGroup.isEmptyChain()) return false;
-      }
-    }
-
-    return true;
-  }
-
   /** Walks a bucket array's raw entries, tombstones included, for an iterator. */
   static final class BucketWalker {
     private Object[] buckets;

internal-api/src/main/java/datadog/trace/api/IdStore.java

@@ -27,6 +27,11 @@ interface Cursor {
     EntryReader next();
   }
 
+  /** A fresh id store reading through to {@code parent}'s known tags (parent may be null). */
+  public static IdStore create(TagMap parent) {
+    return IdStoreFactory.Default.INSTANCE.create(parent == null ? null : parent.knownStore);
+  }
+
   /** Throws for an id that names no known tag. */
   static IllegalArgumentException notKnown(long tagId) {
     return new IllegalArgumentException("not a known tag id: " + Long.toHexString(tagId));