From 7c70af02c446a5cc52abfc03abf981fb2cae8d91 Mon Sep 17 00:00:00 2001 From: Stephen Mallette Date: Fri, 11 Sep 2026 21:00:19 +0000 Subject: [PATCH] Clarify local() side-effect state semantics with a runnable example Add an executable example to the local() step in the Gremlin semantics specification and expand its Considerations to distinguish the local computational state that is reset between executions from global side-effects such as aggregate() and store(), which accumulate across every traverser and are not reset per incoming object. Assisted-by: Kiro:claude-opus-4.8 --- docs/src/dev/provider/gremlin-semantics.asciidoc | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc b/docs/src/dev/provider/gremlin-semantics.asciidoc index 18034f9e4ad..cefa7cc803f 100644 --- a/docs/src/dev/provider/gremlin-semantics.asciidoc +++ b/docs/src/dev/provider/gremlin-semantics.asciidoc @@ -2322,7 +2322,18 @@ None The `local()` step enforces object-local execution. As a branching step with local children, it implements strict lazy evaluation by passing a single traverser at a time to the local traversal (bulk of exactly one, if bulking is supported) -and resetting the traversal to clean state between executions. +and resetting the traversal to clean state between executions. Each incoming object is therefore processed independently, +as illustrated by counting the outgoing edges of every vertex in isolation. + +[gremlin-groovy,modern] +---- +g.V().local(outE().count()) +---- + +The clean state that is reset between executions is the local computational state of the local traversal, such as its +per-object barriers, ordering, and path history. It does not extend to global side effects. A side-effect step such as +`aggregate()` or `store()` writes to a side-effect that is shared across the whole traversal, so its contents are not +reset for each incoming object and instead accumulate across every traverser that passes through `local()`. *Exceptions:*