Reuse setup between examples by linking to a section (ADR 0016)

conformance/adapter/smoke.sh

@@ -64,7 +64,9 @@ oaths_on_disk() {
   [ "$include" = "varar/**/*.md" ] || fail "$dir: the smoke contract assumes oaths live in varar/" \
     "varar.config.json docs.include is [$include]" \
     "Teach smoke.sh to glob, or move the oaths (see CLAUDE.md — 'varar means oaths')."
-  (cd "$REPO_ROOT/$dir" && ls varar/*.md | sort)
+  # `varar/**/*.md` is recursive, and a project may nest oaths (shared sections
+  # referenced from elsewhere conventionally live in varar/shared/ — ADR 0016).
+  (cd "$REPO_ROOT/$dir" && find varar -name '*.md' | sed 's|^\./||' | sort)
 }
 
 run_contract() {

conformance/bundles/20-reference-splice/LibrarySteps.java

@@ -0,0 +1,22 @@
+package dev.varar.conformance.bundle20;
+
+import dev.varar.State;
+import dev.varar.StepDefinitions;
+import dev.varar.Steps;
+
+/** Java sibling of {@code library.steps.ts} / {@code library.steps.py} (bundle {@code 20-reference-splice}). */
+public final class LibrarySteps implements StepDefinitions<LibrarySteps.Ctx> {
+
+    record Ctx(int shelf) implements State {}
+
+    @Override
+    public void register(Steps<Ctx> s) {
+        s.state(() -> new Ctx(0));
+
+        s.stimulus("I shelve {int} books", (Ctx ctx, Integer n) -> new Ctx(ctx.shelf() + n));
+
+        s.stimulus("I borrow a book", (Ctx ctx) -> new Ctx(ctx.shelf() - 1));
+
+        s.sensor("The shelf holds {int} books", (Ctx ctx, Integer n) -> ctx.shelf());
+    }
+}

conformance/bundles/20-reference-splice/example.md

@@ -0,0 +1,7 @@
+# Late fees
+
+A world state written once and linked from the examples that need it.
+
+[A stocked library](./shared.md#a-stocked-library)
+
+I borrow a book. The shelf holds 2 books.

conformance/bundles/20-reference-splice/golden/doc.json

@@ -0,0 +1,108 @@
+{
+  "examples": [
+    {
+      "body": [
+        {
+          "kind": "paragraph",
+          "segmentMap": [
+            {
+              "sourceOffset": 13,
+              "textOffset": 0
+            }
+          ],
+          "span": {
+            "endCol": 70,
+            "endLine": 3,
+            "endOffset": 82,
+            "startCol": 1,
+            "startLine": 3,
+            "startOffset": 13
+          },
+          "text": "A world state written once and linked from the examples that need it."
+        }
+      ],
+      "precededByDelimiter": true,
+      "scopeStack": [
+        "Late fees"
+      ],
+      "span": {
+        "endCol": 70,
+        "endLine": 3,
+        "endOffset": 82,
+        "startCol": 1,
+        "startLine": 3,
+        "startOffset": 13
+      }
+    },
+    {
+      "body": [
+        {
+          "kind": "paragraph",
+          "segmentMap": [
+            {
+              "sourceOffset": 84,
+              "textOffset": 0
+            }
+          ],
+          "span": {
+            "endCol": 51,
+            "endLine": 5,
+            "endOffset": 134,
+            "startCol": 1,
+            "startLine": 5,
+            "startOffset": 84
+          },
+          "text": "[A stocked library](./shared.md#a-stocked-library)"
+        }
+      ],
+      "precededByDelimiter": false,
+      "scopeStack": [
+        "Late fees"
+      ],
+      "span": {
+        "endCol": 51,
+        "endLine": 5,
+        "endOffset": 134,
+        "startCol": 1,
+        "startLine": 5,
+        "startOffset": 84
+      }
+    },
+    {
+      "body": [
+        {
+          "kind": "paragraph",
+          "segmentMap": [
+            {
+              "sourceOffset": 136,
+              "textOffset": 0
+            }
+          ],
+          "span": {
+            "endCol": 42,
+            "endLine": 7,
+            "endOffset": 177,
+            "startCol": 1,
+            "startLine": 7,
+            "startOffset": 136
+          },
+          "text": "I borrow a book. The shelf holds 2 books."
+        }
+      ],
+      "precededByDelimiter": false,
+      "scopeStack": [
+        "Late fees"
+      ],
+      "span": {
+        "endCol": 42,
+        "endLine": 7,
+        "endOffset": 177,
+        "startCol": 1,
+        "startLine": 7,
+        "startOffset": 136
+      }
+    }
+  ],
+  "orphanAttachments": [],
+  "path": "example.md"
+}

conformance/bundles/20-reference-splice/golden/plan.json

@@ -0,0 +1,93 @@
+{
+  "diagnostics": [],
+  "examples": [
+    {
+      "expectedOutcome": "pass",
+      "name": "I borrow a book. The shelf holds 2 books",
+      "scopeStack": [
+        "Late fees"
+      ],
+      "span": {
+        "endCol": 42,
+        "endLine": 7,
+        "endOffset": 177,
+        "startCol": 1,
+        "startLine": 5,
+        "startOffset": 84
+      },
+      "steps": [
+        {
+          "args": [
+            {
+              "parameterType": "int",
+              "value": "3"
+            }
+          ],
+          "docPath": "shared.md",
+          "matchSpan": {
+            "endCol": 17,
+            "endLine": 7,
+            "endOffset": 130,
+            "startCol": 1,
+            "startLine": 7,
+            "startOffset": 114
+          },
+          "matchedExpression": "I shelve {int} books",
+          "paramSpans": [
+            {
+              "endCol": 11,
+              "endLine": 7,
+              "endOffset": 124,
+              "startCol": 10,
+              "startLine": 7,
+              "startOffset": 123
+            }
+          ],
+          "text": "I shelve 3 books"
+        },
+        {
+          "args": [],
+          "matchSpan": {
+            "endCol": 16,
+            "endLine": 7,
+            "endOffset": 151,
+            "startCol": 1,
+            "startLine": 7,
+            "startOffset": 136
+          },
+          "matchedExpression": "I borrow a book",
+          "paramSpans": [],
+          "text": "I borrow a book"
+        },
+        {
+          "args": [
+            {
+              "parameterType": "int",
+              "value": "2"
+            }
+          ],
+          "matchSpan": {
+            "endCol": 41,
+            "endLine": 7,
+            "endOffset": 176,
+            "startCol": 18,
+            "startLine": 7,
+            "startOffset": 153
+          },
+          "matchedExpression": "The shelf holds {int} books",
+          "paramSpans": [
+            {
+              "endCol": 35,
+              "endLine": 7,
+              "endOffset": 170,
+              "startCol": 34,
+              "startLine": 7,
+              "startOffset": 169
+            }
+          ],
+          "text": "The shelf holds 2 books"
+        }
+      ]
+    }
+  ]
+}

conformance/bundles/20-reference-splice/golden/registry.json

@@ -0,0 +1,21 @@
+{
+  "parameterTypes": [],
+  "steps": [
+    {
+      "expression": "I shelve {int} books",
+      "parameterTypeNames": [
+        "int"
+      ]
+    },
+    {
+      "expression": "I borrow a book",
+      "parameterTypeNames": []
+    },
+    {
+      "expression": "The shelf holds {int} books",
+      "parameterTypeNames": [
+        "int"
+      ]
+    }
+  ]
+}

conformance/bundles/20-reference-splice/golden/trace.json

@@ -0,0 +1,43 @@
+{
+  "examples": [
+    {
+      "name": "I borrow a book. The shelf holds 2 books",
+      "outcome": "pass",
+      "steps": [
+        {
+          "contextKey": {
+            "exampleName": "I borrow a book. The shelf holds 2 books",
+            "stepFile": "library.steps"
+          },
+          "exampleName": "I borrow a book. The shelf holds 2 books",
+          "matchedExpression": "I shelve {int} books",
+          "ordinal": 1,
+          "outcome": "pass",
+          "stepText": "I shelve 3 books"
+        },
+        {
+          "contextKey": {
+            "exampleName": "I borrow a book. The shelf holds 2 books",
+            "stepFile": "library.steps"
+          },
+          "exampleName": "I borrow a book. The shelf holds 2 books",
+          "matchedExpression": "I borrow a book",
+          "ordinal": 2,
+          "outcome": "pass",
+          "stepText": "I borrow a book"
+        },
+        {
+          "contextKey": {
+            "exampleName": "I borrow a book. The shelf holds 2 books",
+            "stepFile": "library.steps"
+          },
+          "exampleName": "I borrow a book. The shelf holds 2 books",
+          "matchedExpression": "The shelf holds {int} books",
+          "ordinal": 3,
+          "outcome": "pass",
+          "stepText": "The shelf holds 2 books"
+        }
+      ]
+    }
+  ]
+}

conformance/bundles/20-reference-splice/library.steps.cs

@@ -0,0 +1,28 @@
+// C# sibling of library.steps.ts / .rs (bundle 20-reference-splice).
+using Varar;
+using Varar.Core;
+
+namespace Varar.Corpus.B20;
+
+public static class LibrarySteps
+{
+    public static void Register(Steps s)
+    {
+        s.Stimulus(
+            "I shelve {int} books",
+            (state, n) => Value.Map([new("shelf", Value.Of(ShelfOf(state) + AsLong(n)))]));
+
+        s.Stimulus(
+            "I borrow a book",
+            state => Value.Map([new("shelf", Value.Of(ShelfOf(state) - 1))]));
+
+        s.Sensor("The shelf holds {int} books", (state, n) => Value.Of(ShelfOf(state)));
+    }
+
+    public static Value State() => Value.Map([new("shelf", Value.Of(0))]);
+
+    private static long ShelfOf(Value state) =>
+        state is VMap m && m.Entries.TryGetValue("shelf", out var v) && v is VInt i ? i.Int : 0;
+
+    private static long AsLong(Value v) => v is VInt i ? i.Int : 0;
+}

conformance/bundles/20-reference-splice/library.steps.go

@@ -0,0 +1,31 @@
+// Go sibling of library.steps.ts (bundle 20-reference-splice).
+package fixture
+
+import "github.com/varar-dev/varar/go/varar"
+
+func shelfOf(state varar.Value) int {
+	if m, ok := state.AsMap(); ok {
+		if c, ok := m["shelf"]; ok {
+			if n, ok := c.AsInt(); ok {
+				return int(n)
+			}
+		}
+	}
+	return 0
+}
+
+func Register(s *varar.Steps[varar.Value]) {
+	s.Stimulus("I shelve {int} books", func(state varar.Value, n int) (varar.Value, error) {
+		return varar.MapValue(map[string]varar.Value{"shelf": varar.IntValue(int64(shelfOf(state) + n))}), nil
+	})
+	s.Stimulus("I borrow a book", func(state varar.Value) (varar.Value, error) {
+		return varar.MapValue(map[string]varar.Value{"shelf": varar.IntValue(int64(shelfOf(state) - 1))}), nil
+	})
+	s.Sensor("The shelf holds {int} books", func(state varar.Value, expected int) (int, error) {
+		return shelfOf(state), nil
+	})
+}
+
+func State() varar.Value {
+	return varar.MapValue(map[string]varar.Value{"shelf": varar.IntValue(0)})
+}

conformance/bundles/20-reference-splice/library.steps.kt

@@ -0,0 +1,17 @@
+@file:JvmName("LibrarySteps")
+
+// Kotlin sibling of library.steps.ts / library.steps.py / LibrarySteps.java
+// (bundle 20-reference-splice).
+package dev.varar.kotlin.conformance.bundle20
+
+import dev.varar.kotlin.stimulus
+import dev.varar.kotlin.steps
+import dev.varar.kotlin.sensor
+
+data class Ctx(val shelf: Int = 0)
+
+val steps = steps(::Ctx) {
+    stimulus("I shelve {int} books") { n: Int -> copy(shelf = shelf + n) }
+    stimulus("I borrow a book") { copy(shelf = shelf - 1) }
+    sensor("The shelf holds {int} books") { n: Int -> shelf }
+}