[TINKERPOP-3261] Enable multiple labels on vertex with configurable label cardinality

CHANGELOG.asciidoc

@@ -44,6 +44,13 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Changed `Tree` to no longer extend `HashMap`; it is now a final class with a tree-shaped API (`childAt`, `hasChild`, `contains`, `findSubtree`, `getOrCreateChild`, `getNodesAtDepth`, `getLeafNodes`, `nodeCount`) and is no longer a `Map`.
 * Changed `count(local)` on a `Tree` to return the total node count (`Tree.nodeCount()`) instead of the root-entry count.
 * Changed Tree class in Java to not extend from HashMap and offered a new tree-shaped API for navigation.
+* Added multi-label support for vertices with configurable `LabelCardinality` (`ONE`, `ONE_OR_MORE`, `ZERO_OR_MORE`).
+* Added `labels()` step to emit each vertex label as a separate traverser.
+* Added `addLabel()` and `dropLabel()`/`dropLabels()` steps for vertex label mutation.
+* Added `LabelCardinalityValidator` utility for constraint enforcement separated from the `LabelCardinality` enum.
+* Added `with("multilabel")` source configuration for `elementMap()` and `valueMap()` to return labels as a set.
+* Added `labels().drop()` rejection to `StandardVerificationStrategy` to prevent accidental usage.
+* Added multi-label syntax to `addV()` and `mergeV()` with append-only `onMatch` semantics.
 * Added typed numeric wrappers and `preciseNumbers` connection option to `gremlin-javascript` for explicit control over numeric type serialization and deserialization.
 * Added `NextN(n)` to `Traversal` in `gremlin-go` for batched result iteration, providing API parity with `next(n)` in the Java, Python, and .NET GLVs, and updated the Go translators in `gremlin-core` and `gremlin-javascript` to emit `NextN(n)` for the batched form.
 * Added Provider Defined Types (PDT) support — graph providers can define custom types via `@ProviderDefined` annotation that serialize/deserialize seamlessly across all GLVs without driver-side configuration. Replaces TP3 custom type mechanism.

docker/gremlin-server/gremlin-server-integration.yaml

@@ -23,6 +23,9 @@ graphs: {
   graph: {
     configuration: conf/tinkergraph-service.properties,
     traversalSources: [{name: g}, {name: ggraph}]},
+  multilabel: {
+    configuration: conf/tinkergraph-multilabel.properties,
+    traversalSources: [{name: gmultilabel}]},
   immutable: {
     configuration: conf/tinkergraph-service.properties,
     traversalSources: [{name: gimmutable}]},

docs/src/dev/developer/for-committers.asciidoc

@@ -672,8 +672,17 @@ TinkerGQL support out of the box and runs these scenarios without any additional
 * `@InsertionOrderingRequired` - The scenario is reliant on the graph system predictably returning results (vertices,
 edges, properties) in the same order in which they were inserted into the graph.
 * `@MetaProperties` - The scenario makes use of meta-properties.
+* `@MultiLabel` - The scenario requires a graph that supports multiple labels per vertex (i.e.
+`ONE_OR_MORE` or `ZERO_OR_MORE` vertex label cardinality). Providers that only support single-label vertices
+should exclude these tests.
+* `@MultiLabelDefault` - The scenario assumes a graphs unconfigured `valueMap()`/`elementMap()` steps
+produce results following `with("multilabel")` semantics. Graphs which default to `with("singlelabel")` semantics
+should exclude these tests.
 * `@MultiProperties` - The scenario makes use of multi-properties.
 * `@SupportsChar` - The scenario requires that `char` is completely supported.
+* `@SingleLabelDefault` - The scenario assumes a graphs unconfigured `valueMap()`/`elementMap()` steps
+produce results following `with("singlelabel")` semantics. Graphs which default to `with("multilabel")` semantics
+should exclude these tests.
 * `@SupportsDuration` - The scenario requires that `Duration` is completely supported.
 * `@SupportsBinary` - The scenario requires that `Binary` is completely supported.
 * `@UserSuppliedVertexIds` - The scenario relies on the vertex IDs specified in the dataset used by the scenario.

docs/src/dev/provider/gremlin-semantics.asciidoc

@@ -587,6 +587,84 @@ See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/j
 link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AddVertexStartStep.java[source (start)],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#addvertex-step[reference]
 
+=== addLabel()
+
+*Description:* Adds one or more labels to an element.
+
+*Syntax:* `addLabel(String label, String... moreLabels)` | `addLabel(Traversal<?, ?> labelTraversal, Traversal<?, ?>... moreLabelTraversals)`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |N |`Element` |`Element`
+|=========================================================
+
+*Arguments:*
+
+* `label` - The label to add.
+* `moreLabels` - Additional labels to add.
+* `labelTraversal` - The first (or only) traversal that produces a label to add.
+* `moreLabelTraversals` - Additional label-producing traversals (may be empty for single-traversal behavior).
+
+*Considerations:*
+
+Label add and remove operations require a `LabelCardinality` that permits changing the set of labels on an element
+(`ONE_OR_MORE` or `ZERO_OR_MORE`). When `LabelCardinality` is `ONE`, the vertex's label is fixed at creation and
+cannot be added to or removed.
+Adding a label that already exists on the element is a no-op. The step returns the element (sideEffect semantics).
+Each traversal argument is iterated for a single result only. If exactly one traversal is provided and it produces
+a `Collection<String>`, the collection will be automatically unfolded into the set of labels added; if more than one
+traversal is provided, each must resolve to a single `String` label.
+
+*Exceptions*
+
+* If the graph's `LabelCardinality` does not permit label modification, an `IllegalStateException` will be thrown.
+* If any label argument is null or empty, an `IllegalArgumentException` will be thrown.
+* If more than one traversal is provided and any of them produces a `Collection`, an `IllegalArgumentException` will
+be thrown.
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/sideEffect/AddLabelStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#addlabel-step[reference]
+
+=== dropLabel()
+
+*Description:* Removes one or more specific labels from an element, or removes all labels.
+
+*Syntax:* `dropLabel(String label, String... moreLabels)` | `dropLabel(Traversal<?, String> labelTraversal, Traversal<?, String>... moreLabelTraversals)` | `dropLabels()`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |N |`Element` |`Element`
+|=========================================================
+
+*Arguments:*
+
+* `label` - The label to remove.
+* `moreLabels` - Additional labels to remove.
+* `labelTraversal` - The first (or only) traversal that produces a label to remove.
+* `moreLabelTraversals` - Additional label-producing traversals (may be empty for single-traversal behavior).
+
+*Considerations:*
+
+Label add and remove operations require a `LabelCardinality` that permits changing the set of labels on an element
+(`ONE_OR_MORE` or `ZERO_OR_MORE`). Dropping a label that does not exist
+on the element is a no-op. `dropLabels()` removes all labels (only valid with `ZERO_OR_MORE`). The step returns the
+element (sideEffect semantics).
+Each traversal argument is iterated for a single result only. If exactly one traversal is provided and it produces
+a `Collection<String>`, the collection will be automatically unfolded into the set of labels removed; if more than
+one traversal is provided, each must resolve to a single `String` label.
+
+*Exceptions*
+
+* If the graph's `LabelCardinality` does not permit label modification, an `IllegalStateException` will be thrown.
+* If `dropLabel()` or `dropLabels()` would violate the minimum label count, an `IllegalStateException` will be thrown.
+* If more than one traversal is provided and any of them produces a `Collection`, an `IllegalArgumentException` will
+be thrown.
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/sideEffect/DropLabelsStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#droplabel-step[reference]
+
 [[all-step]]
 === all()
 
@@ -1637,6 +1715,52 @@ See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/j
 link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/sideEffect/GroupCountSideEffectStep.java[source (sideEffect)],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#groupcount-step[reference]
 
+[[label-step]]
+=== label()
+
+*Description:* Maps an element to its label as a single string value.
+
+*Syntax:* `label()`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |N |`Element` |`String`
+|=========================================================
+
+*Considerations:*
+
+The `label()` step returns exactly one label string per element. For graphs that support multiple labels per vertex,
+`label()` returns only one of the vertex's labels and the choice is non-deterministic (implementation-dependent
+ordering). Use `labels()` to retrieve all labels reliably.
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LabelStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#label-step[reference]
+
+[[labels-step]]
+=== labels()
+
+*Description:* Maps an element to its labels, emitting one traverser per label.
+
+*Syntax:* `labels()`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |N |`Element` |`String`
+|=========================================================
+
+*Considerations:*
+
+For vertices with a single label, `labels()` emits one traverser (equivalent to `label()`). For multi-label vertices,
+it emits one traverser per label. For vertices with zero labels (`ZERO_OR_MORE` mode), no traversers are emitted.
+
+`hasLabel("a", "b")` uses OR semantics: it matches any vertex that has label "a" or label "b". To match vertices
+with all specified labels, chain calls: `hasLabel("a").hasLabel("b")`.
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LabelsStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#labels-step[reference]
+
 [[length-step]]
 === length()
 
@@ -2564,6 +2688,13 @@ the possible values are:
 ** 8 for including values (VertexProperty)
 ** 15 for including all
 
+The label format in the map is controlled by source-level `with("multilabel")` and `with("singlelabel")` options, not
+by the graph's `LabelCardinality`. When `"multilabel"` is present and `"singlelabel"` is not, the label value is a
+`Set<String>`; otherwise it is a single `String`. As a deliberate design choice, when both options are present on the
+same source, `"singlelabel"` always takes precedence regardless of the order in which they were applied. This ensures
+deterministic behavior rather than relying on declaration order. Providers who want label output tied to their
+cardinality configuration should override `PropertyMapStep` and/or `ElementMapStep`.
+
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/PropertyMapStep.java[source],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#valuemap-step[reference],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#propertymap-step[reference]

docs/src/reference/implementations-tinkergraph.asciidoc

@@ -166,6 +166,7 @@ TinkerGraph has several settings that can be provided on creation via `Configura
 |gremlin.tinkergraph.vertexPropertyIdManager |The `IdManager` implementation to use for vertex properties.
 |gremlin.tinkergraph.defaultVertexPropertyCardinality |The default `VertexProperty.Cardinality` to use when `Vertex.property(k,v)` is called.
 |gremlin.tinkergraph.allowNullPropertyValues |A boolean value that determines whether or not `null` property values are allowed and defaults to `false`.
+|gremlin.tinkergraph.vertexLabelCardinality |The `LabelCardinality` for vertices. Options are `ONE` (default, single immutable label, backward-compatible with 3.x), `ONE_OR_MORE` (at least one label, mutable), or `ZERO_OR_MORE` (zero or more labels). See <<tinkergraph-multi-label>>.
 |gremlin.tinkergraph.graphLocation |The path and file name for where TinkerGraph should persist the graph data. If a
 value is specified here, the `gremlin.tinkergraph.graphFormat` should also be specified.  If this value is not
 included (default), then the graph will stay in-memory and not be loaded/persisted to disk.
@@ -219,6 +220,35 @@ g.io("data/tinkerpop-crew.kryo").read().iterate()
 g.V().properties()
 ----
 
+[[tinkergraph-multi-label]]
+=== Multi-Label Support
+
+TinkerGraph supports multiple labels per vertex when `gremlin.tinkergraph.vertexLabelCardinality` is set to
+`ONE_OR_MORE` or `ZERO_OR_MORE`. This enables use of the `addLabel()`, `dropLabel()`, `dropLabels()`, and `labels()`
+traversal steps.
+
+[gremlin-groovy]
+----
+conf = new BaseConfiguration()
+conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
+graph = TinkerGraph.open(conf)
+g = traversal().with(graph)
+g.addV("person","employee").property("name","marko").iterate()
+g.V().has("name","marko").labels() <1>
+g.V().has("name","marko").addLabel("manager").labels() <2>
+g.V().has("name","marko").dropLabel("employee").labels() <3>
+----
+
+<1> The vertex was created with two labels.
+<2> A third label is added.
+<3> One label is removed.
+
+The `hasLabel()` step works with multi-label vertices using OR semantics: `hasLabel("a","b")` matches any vertex that
+has label "a" OR label "b". To match vertices having both labels, chain multiple `hasLabel()` calls:
+`hasLabel("a").hasLabel("b")`.
+
+IMPORTANT: Edges always have exactly one label — multi-label support applies to vertices only.
+
 [[tinkergraph-gremlin-tx]]
 === Transactions
 

docs/src/reference/the-graph.asciidoc

@@ -179,6 +179,17 @@ g.V().has('name','gremlin').inE('uses').
       select('a','b').by('skill').by('name') // rank the users of gremlin by their skill level
 ----
 
+[[vertex-labels]]
+=== Vertex Labels
+
+In addition to multi-properties and meta-properties, TinkerPop supports multiple labels on a single vertex. The number
+of labels a vertex may carry is governed by the graph's configured `LabelCardinality`: `ONE` fixes exactly one immutable
+label per vertex (the traditional model), `ONE_OR_MORE` requires at least one label but permits additional labels to be
+added or removed, and `ZERO_OR_MORE` allows a vertex to have any number of labels including none. See the
+link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#_label_cardinality[provider documentation] for configuration
+details and the <<label-step,label()>>, <<labels-step,labels()>>, <<addlabel-step,addLabel()>>, and
+<<droplabel-step,dropLabel()>> steps for traversal access.
+
 == Graph Variables
 
 `Graph.Variables` are key/value pairs associated with the graph itself -- in essence, a `Map<String,Object>`. These