Major Refactoring: Interceptor Architecture & Iterator-based Responses

.gitignore

@@ -20,13 +20,21 @@ Session.vim
 .netrwhist
 *~
 
-*.xo
+# IDE and scratch files
 .vscode/*.log
 .idea/
+*.xo
 z-scratch/
 
-# binary files
+# Binary files
 cmd/benchmark/benchmark
+examples/storage/storage
+
+# Gorums generated backup files
 cmd/protoc-gen-gorums/gengorums/template_static.go.bak
 
+# Ignore the generated code for the tutorial example
+examples/gorumsexample/storage.pb.go
+examples/gorumsexample/storage_gorums.pb.go
+
 go.work.sum

.vscode/extensions.json

@@ -1,11 +1,9 @@
 {
     "recommendations": [
-        "xaver.clang-format",
         "streetsidesoftware.code-spell-checker",
         "golang.go",
         "davidanson.vscode-markdownlint",
-        "zxh404.vscode-proto3",
-        "github.vscode-pull-request-github",
-        "redhat.vscode-yaml"
+        "drblury.protobuf-vsc",
+        "github.vscode-pull-request-github"
     ]
 }

.vscode/gorums.txt

@@ -1,5 +1,7 @@
 Ansible
 benchgraph
+benchtest
+benchtime
 bootstrapgorums
 calltype
 calltypes
@@ -19,6 +21,7 @@ errgroup
 extendee
 Frausing's
 fset
+GCFLAGS
 gengorums
 genproto
 GOBIN
@@ -51,11 +54,14 @@ memprofile
 mktemp
 multicast
 naddr
+netrwhist
 obj's
+objc
 oneway
 Paxos
 Pedersen
 pkgs
+pluginpb
 proto
 protobuf
 protoc
@@ -78,10 +84,13 @@ RPC's
 RPCs
 semver
 shlex
+skipcq
 srvs
 stressdev
 stressgen
+stresstest
 struct
+subtests
 syncrq
 testprotos
 testrace

.vscode/settings.json

@@ -30,6 +30,7 @@
     },
     "files.exclude": {
         "**/.git": true,
+        "**/.jj": true,
         "**/.DS_Store": true,
     },
     "files.insertFinalNewline": true,
@@ -53,19 +54,24 @@
         "usePlaceholders": true,
         "staticcheck": false
     },
-    "protoc": {
-        "compile_on_save": false,
-        "options": [
-            "--proto_path=${workspaceRoot}",
-            "--proto_path=${workspaceRoot}/cmd/protoc-gen-gorums/dev",
-            "--proto_path=${workspaceRoot}/third_party"
-        ]
-    },
-    "clang-format.executable": "/usr/bin/clang-format",
-    "clang-format.style": "{ IndentWidth: 4, BasedOnStyle: google, AlignConsecutiveAssignments: true, ColumnLimit: 120 }",
-    "[proto3]": {
-        "editor.defaultFormatter": "zxh404.vscode-proto3"
-    },
+    "protobuf.protoc.path": "protoc",
+    "protobuf.formatOnSave": true,
+    "protobuf.formatter.enabled": true,
+    "protobuf.formatter.alignFields": true,
+    "protobuf.protoc.options": [
+        "--proto_path=${workspaceFolder}",
+        "--proto_path=${workspaceFolder}/cmd/protoc-gen-gorums/dev",
+        "--proto_path=${workspaceFolder}/third_party",
+        "--go_opt=paths=source_relative",
+        "--go-grpc_opt=paths=source_relative",
+        "--gorums_opt=paths=source_relative",
+        "--go_opt=default_api_level=API_OPAQUE"
+    ],
+    "protobuf.buf.path": "buf",
+    "protobuf.externalLinter.bufPath": "buf",
+    "protobuf.externalLinter.enabled": true,
+    "protobuf.externalLinter.runOnSave": true,
+    "protobuf.externalLinter.linter": "buf",
     "markdownlint.config": {
         "MD024": false,
         "default": true,

AGENTS.md

@@ -1,6 +1,7 @@
 # Agent Instructions for Gorums Project
 
-You are working on the Gorums project - a framework for building fault-tolerant distributed systems using quorum-based abstractions. This document provides critical context and rules for AI coding assistants.
+Gorums is a framework for building fault-tolerant distributed systems using quorum-based abstractions.
+This document provides context and rules for AI coding assistants.
 
 ## Project Overview
 
@@ -34,7 +35,7 @@ gorums/
 └── *.go                       # Core library files
 ```
 
-## Critical Development Rules
+## Development Rules
 
 ### Code Generation Workflow
 
@@ -43,28 +44,26 @@ gorums/
 These files are generated from templates. Instead:
 
 1. **For Template Changes:**
-   - Edit the corresponding template in `cmd/protoc-gen-gorums/gengorums/template_*.go`
-   - Run `make` to regenerate code
-   - The `zorums_*` files will be automatically updated
+   - Edit template in `cmd/protoc-gen-gorums/gengorums/template_*.go`
+   - Run `make dev` to regenerate `zorums_*_gorums.pb.go` files
 
 2. **For Static Code Changes:**
    - Edit files in `cmd/protoc-gen-gorums/dev/` that are NOT prefixed with `zorums_*`
-   - Run `make` to bundle changes into `template_static.go`
-   - Changes propagate to generated code automatically
+   - Run `make dev` to bundle changes into `template_static.go`
 
 3. **After Any Template or Static Code Changes:**
-
-   ```bash
-   make          # Normal rebuild
-   make -B       # Force rebuild (e.g., after protoc update)
-   ```
+   - Run `make dev` to regenerate `zorums_*_gorums.pb.go` files
+   - Or run `make genproto` to regenerate all _gorums.pb.go files
 
 ### Testing Requirements
 
 - **Run tests after every change:** `make test`
 - Tests verify the correctness and stability of generated code
 - ALL test failures must be addressed before considering work complete
 - Never delete failing tests - fix the underlying issue
+- If suitable, tests should be table-driven
+- If suitable, tests should be organized as subtests
+- Test names should be capitalized, like TestFileNameFeatureName, e.g., TestQuorumCallFeatureName, for some feature in `quorumcall_test.go`
 
 ### Code Style and Conventions
 
@@ -105,6 +104,12 @@ These files are generated from templates. Instead:
 ### Common Commands
 
 ```bash
+# Generate `zorums_*_gorums.pb.go` files in `cmd/protoc-gen-gorums/dev/`
+make dev
+
+# Generate _gorums.pb.go files across the project
+make genproto
+
 # Build everything
 make
 
@@ -114,6 +119,9 @@ make -B
 # Run tests
 make test
 
+# Ensure tests are actually run (not skipped by cache)
+go test ./... -count=1
+
 # Install protoc-gen-gorums plugin
 make installgorums
 
@@ -152,7 +160,7 @@ Gorums provides custom protobuf options defined in `gorums.proto`:
 
 - Method-level options for quorum call types
 - Configuration options for RPC behavior
-- See `doc/method-options.md` for details
+- See `doc/user-guide.md` for details
 
 ## Documentation
 
@@ -161,8 +169,9 @@ Before making significant changes, consult:
 - `doc/user-guide.md` - Understanding the API and usage patterns
 - `doc/dev-guide.md` - Development workflow and architecture
 - `doc/design-doc-layering.md` - System architecture and layering
-- `doc/method-options.md` - Protocol buffer options reference
+
 - `README.md` - Project overview and getting started
+- When editing markdown files, use one sentences per line, so that diffs are easier to read.
 
 ## Common Pitfalls to Avoid
 

Makefile

@@ -7,11 +7,11 @@ static_file				:= $(gen_path)/template_static.go
 static_files			:= $(shell find $(dev_path) -name "*.go" -not -name "zorums*" -not -name "*_test.go")
 proto_path 				:= $(dev_path):third_party:.
 
-plugin_deps				:= gorums.pb.go internal/correctable/opts.pb.go $(static_file)
+plugin_deps				:= gorums.pb.go $(static_file)
 runtime_deps			:= ordering/ordering.pb.go ordering/ordering_grpc.pb.go
 benchmark_deps			:= benchmark/benchmark.pb.go benchmark/benchmark_gorums.pb.go
 
-.PHONY: all dev tools bootstrapgorums installgorums benchmark test compiletests genproto
+.PHONY: all dev tools bootstrapgorums installgorums benchmark test compiletests genproto benchtest bench
 
 all: dev benchmark compiletests
 
@@ -56,12 +56,35 @@ endif
 compiletests: installgorums
 	@$(MAKE) --no-print-directory -C ./internal/tests all
 
-test: compiletests
+test: compiletests benchtest
 	@go test ./...
 
 testrace: compiletests
 	go test -race -cpu=1,2,4 ./...
 
+# Run benchmarks with validation (short runs to verify they don't fail).
+# Uses -benchtime=100x for limited iterations to avoid port exhaustion on macOS.
+# Suppresses output on success; shows details on failure.
+benchtest: compiletests
+	@if ! go test -run=^$$ -bench=. -benchtime=100x -count=1 ./... > /tmp/benchtest.out 2>&1; then \
+		echo "Benchmark validation failed:"; \
+		cat /tmp/benchtest.out; \
+		exit 1; \
+	fi
+	@echo "Benchmark validation passed"
+
+# Run benchmarks with proper measurement (longer runs for performance analysis).
+# Use -count=10 or more for statistically significant results.
+# This only runs benchmarks in the main module and in internal/tests/oneway
+# (when adding benchmarks elsewhere, update this target accordingly).
+bench: compiletests
+	go test -run=^$$ -bench=. -benchtime=1s -count=10 . ./internal/tests/oneway
+
+# Run stress tests that use longer durations for thorough testing.
+# These tests are excluded from normal test runs via the 'stress' build tag.
+stresstest: compiletests
+	go test -tags=stress ./...
+
 # Warning: will probably run for 10 minutes; the timeout does not work
 stressdev: tools
 	go test -c $(dev_path)