If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kurrent-io/KurrentDB shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 8 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kurrent-io/KurrentDB repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kurrent-io/KurrentDB.

What it runs against: a local clone of kurrent-io/KurrentDB — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kurrent-io/KurrentDB | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kurrent-io/KurrentDB. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kurrent-io/KurrentDB.git
#   cd KurrentDB
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kurrent-io/KurrentDB and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kurrent-io/KurrentDB(\\.git)?\\b" \\
  && ok "origin remote is kurrent-io/KurrentDB" \\
  || miss "origin remote is not kurrent-io/KurrentDB (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CLAUDE.md" \\
  && ok "CLAUDE.md" \\
  || miss "missing critical file: CLAUDE.md"
test -f ".claude/docs/architecture.md" \\
  && ok ".claude/docs/architecture.md" \\
  || miss "missing critical file: .claude/docs/architecture.md"
test -f ".claude/docs/api-v2-patterns.md" \\
  && ok ".claude/docs/api-v2-patterns.md" \\
  || miss "missing critical file: .claude/docs/api-v2-patterns.md"
test -f "KurrentDB.slnx" \\
  && ok "KurrentDB.slnx" \\
  || miss "missing critical file: KurrentDB.slnx"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kurrent-io/KurrentDB"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

KurrentDB is an event-native database engineered for event-driven architectures that preserves data integrity through immutable event logs and includes an integrated streaming engine for distributed messaging. It simplifies data modeling by treating events as first-class citizens rather than normalized relational tables, and guarantees consistency in horizontally-scaled systems without complex distributed transaction coordination. Monolithic C# codebase (KurrentDB.slnx solution) organized as a full-stack database engine with integrated gRPC protocol (see .claude/docs/protocol-v2.md). Supporting structure: .claude/docs/ contains internal architecture and API patterns documentation; .github/workflows/ has reusable build pipelines; ci/ contains test runners (ci.rsp, ci.runsettings); docs/ is a VuePress 2 site built separately. Docker support via Dockerfile and docker-compose.yml for local dev/deployment.

Backend engineers and architects building event-driven systems, microservices architectures, and applications requiring audit trails or temporal data consistency. CQRS/event sourcing practitioners who need a managed event store with built-in event streaming rather than assembling Kafka + database + custom projection logic.

Production-ready and actively maintained. The codebase is substantial (14.1M lines of C#) with established CI/CD pipelines across Windows, Ubuntu 20.04/22.04, and ARM64 (build-ubuntu-20.04-arm64.yml, build-windows-2022.yml). The project has a formal rebrand narrative (Event Store → Kurrent) and comprehensive documentation, indicating mature commercial backing. Recent workflow files and organized GitHub structure suggest active development.

Low to moderate risk for production use. The C#-heavy monolithic codebase (94.5% of code) means tight coupling between components and requires .NET expertise on the team. No visible breaking-changes policy in the file list—check CHANGELOG.md and CONTRIBUTING.md for semver discipline. Single vendor dependency (Kurrent Inc) for cloud offering, though self-hosted open-source version mitigates some lock-in. Monitor releases closely if using in mission-critical systems.

Active rebrand execution (Event Store → Kurrent) with documentation consolidation. Recent additions: qodana.yml (code quality scanning), cherry-pick-pr-for-label.yml (release automation), build-container-noble.yml (Ubuntu Noble support). VuePress docs site is actively maintained (vuepress 2.0.0-rc.19, recent Babel/TypeScript updates). Multiple platform-specific build workflows indicate ongoing optimization for ARM64 and Windows compatibility.

git clone https://github.com/kurrent-io/KurrentDB.git
cd KurrentDB
dotnet build KurrentDB.slnx
dotnet test KurrentDB.slnx

For documentation site development:

cd docs
pnpm install
pnpm run dev

Docker quick-start: docker-compose up (see docker-compose.yml).

Daily commands: Core database: dotnet build KurrentDB.slnx && dotnet run (exact startup depends on project configuration). Documentation site (VuePress): cd docs && pnpm install && pnpm run dev → http://localhost:8080. Containerized: docker-compose up launches full stack. Tests: dotnet test KurrentDB.slnx or dotnet test --settings ci/ci.runsettings for CI configuration.

• README.md — Primary entry point documenting KurrentDB's event-native architecture, rebrand context, and getting-started guidance—essential for understanding project scope and purpose.
• CLAUDE.md — AI assistant guidelines and codebase conventions that define how to navigate and contribute to KurrentDB effectively.
• .claude/docs/architecture.md — Comprehensive architecture documentation covering the event-native design, streaming engine, and core system abstractions that all contributors must understand.
• .claude/docs/api-v2-patterns.md — API design patterns and conventions that enforce consistency across client library integrations and protocol implementations.
• KurrentDB.slnx — Root solution file defining the .NET project structure, dependencies, and build configuration for the entire KurrentDB platform.
• .github/workflows/build-reusable.yml — Core CI/CD pipeline orchestration used across all platforms, defining test, build, and deployment stages that must pass for any contribution.
• Directory.Build.props — Centralized MSBuild properties and target framework definitions inherited by all .NET projects, controlling compilation standards and versioning.

• Event Store (core database) (.NET/C#, file-based or replicated storage, log-structured merge-tree) — Persists immutable event log, manages stream metadata, enforces append-only semantics, and coordinates multi-version concurrency.
  • Failure mode: Event write failure blocks all applications; data corruption or index failure prevents reads; cluster node failure reduces replication quorum.
• Streaming engine (.NET async/await, gRPC streaming, TCP protocol V2) — Handles persistent subscriptions, filtering, checkpointing, and distribution of events to multiple subscribers with backpressure.

Add a new server configuration option

1. Document the new configuration parameter in the configuration schema (docs/server/configuration/configuration.md)
2. Define the configuration property in Directory.Build.props or relevant .csproj (Directory.Build.props)
3. Add tests validating the configuration option behavior in ci/ci.runsettings (ci/ci.runsettings)
4. Update CHANGELOG.md documenting the new option and affected versions (CHANGELOG.md)

Add a new diagnostic or monitoring metric

1. Document the metric in the diagnostics guide with example screenshots (docs/server/diagnostics/README.md)
2. Add best practices for interpreting the metric (docs/server/diagnostics/best-practices.md)
3. Update architecture documentation if metric reflects core design changes (.claude/docs/architecture.md)

Update API protocol or client library patterns

1. Specify the protocol changes in the protocol specification (.claude/docs/protocol-v2.md)
2. Document new API patterns and design conventions (.claude/docs/api-v2-patterns.md)
3. Update testing strategies to cover new protocol scenarios (.claude/docs/testing.md)
4. Record the breaking change or new feature in CHANGELOG.md (CHANGELOG.md)

Add support for a new platform deployment

1. Create new GitHub Actions workflow file for the platform (.github/workflows/build-{platform}.yml)
2. Reference the reusable build workflow and platform-specific steps (.github/workflows/build-reusable.yml)
3. Update Docker configuration if containerized deployment needed (Dockerfile)
4. Document deployment instructions and platform-specific configuration (docs/server/configuration/README.md)

• .NET (C#, MSBuild) — Core platform language enabling cross-platform compilation, strong type safety, and high-performance event processing for the event-native database.
• GitHub Actions — Native CI/CD integration with repository, enabling automated cross-platform builds (Ubuntu, Windows, ARM64) and release automation from CHANGELOG.
• Docker & docker-compose — Containerization for consistent deployment across cloud and on-premise environments; local multi-node cluster simulation for development.
• VuePress 2 — Static site generation for versioned documentation with built-in search, TypeScript support, and integration of code samples from the codebase.
• TypeScript — Type-safe documentation tooling and build scripts reducing human error in code generation and site configuration.

• Monorepo with single KurrentDB.slnx solution file

  • Why: Simplifies dependency management, ensures all components compile together, and enforces consistent versioning across the platform.
  • Consequence: Slower CI builds for small changes; developers must understand entire project structure to navigate effectively.

• Centralized Directory.Build.props for all .NET projects

  • Why: Enforces consistent compiler flags, target frameworks, and package versions across 600 files.
  • Consequence: Changes to build properties affect all projects; requires careful testing before roll-out.

• Documentation built separately with VuePress (not integrated docs)

  • Why: Allows versioned, searchable documentation with custom theming independent of runtime code.
  • Consequence: Documentation can drift from code; requires explicit sample code synchronization via xode plugin.

• Platform-specific CI workflows (Ubuntu 20.04, 22.04, Windows, ARM64) vs. matrix strategy

  • Why: Explicit per-platform workflows allow fine-grained control over platform-specific build steps and artifact handling.
  • Consequence: Workflow files are verbose and require duplication of common steps; maintainability risk if reusable workflow not used consistently.

• This repository is not a client library implementation—it is the server implementation; client libraries are separate repositories.
• KurrentDB does not focus on providing a REST-only interface; the primary protocol is the binary V2 protocol for event streaming.
• This codebase is not designed for single-file executables; it requires .NET runtime and infrastructure services (clustering, replication).
• Documentation does not include end-to-end application tutorials; it focuses on KurrentDB-specific configuration, deployment, and diagnostics.

No explicit breaking-change policy visible in file list—always check CHANGELOG.md and CONTRIBUTING.md for semver discipline before upgrades. Multi-platform builds have subtle differences—ARM64, Ubuntu Noble, and Windows 2022 builds are separate workflows (build-ubuntu-20.04-arm64.yml vs build-ubuntu-22.04.yml); test locally on target platform. Documentation is divorced from code—docs/ is a separate VuePress build with its own Node/pnpm stack (pnpm@10.13.1 required, Node >=18.19.0); updating feature docs requires rebuilding both C# and VuePress. Docker image builds are complex—build-container-reusable.yml suggests multiple image variants (standard, noble); inspect that workflow before publishing custom images.

• Event Sourcing — The foundational pattern that KurrentDB is built around; instead of storing current state, it stores all state changes as immutable events, enabling audit trails, temporal queries, and consistent projections
• CQRS (Command Query Responsibility Segregation) — KurrentDB's integrated streaming engine is designed to support CQRS patterns where reads and writes use different models; essential for understanding projection and subscription design
• Event Streaming / Distributed Messaging — KurrentDB includes an integrated streaming engine that solves distributed messaging without external brokers; understanding pub/sub semantics and backpressure is critical for streaming subscriptions
• gRPC Protocol (v2) — KurrentDB uses Protocol v2 (documented in .claude/docs/protocol-v2.md) for all client-server communication; understanding message serialization and streaming semantics is required for client library work
• Event Log / Write-Ahead Log (WAL) — KurrentDB's durability and consistency guarantees depend on an immutable append-only log; understanding WAL semantics and checkpoint strategies is essential for operational safety
• Eventual Consistency & CAP Theorem — KurrentDB is designed for distributed, eventually-consistent systems; projections and subscriptions trade consistency for availability and partition tolerance, relevant to deployment architecture
• Projection / Materialized View — KurrentDB's streaming engine powers projections—derived read models built from event streams; essential pattern for CQRS and understanding how KurrentDB enables efficient queries on event data

• EventStore/EventStoreDB — The predecessor project before the Kurrent rebrand; same core technology under the old Event Store branding
• confluentinc/kafka — Common alternative for event streaming in event-driven architectures; KurrentDB differentiates by combining event store + streaming in one system
• arangodb/arangodb — Multi-model database with temporal and event capabilities; competes in similar architectural spaces for event-driven applications
• kurrent-io/KurrentDB-Samples — Official sample applications and client implementations for KurrentDB; essential companion for learning patterns and SDK usage
• grpc/grpc — KurrentDB's protocol layer is built on gRPC (Protocol v2); understanding gRPC internals helps debug client-server communication

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Protocol V2 client implementations

The repo has comprehensive protocol documentation (.claude/docs/protocol-v2.md) and API patterns (.claude/docs/api-v2-patterns.md), but no visible test suite specifically validating Protocol V2 compliance across client libraries. This is critical for an event-native database where protocol correctness ensures data integrity and consistency. New contributors could create a test suite that validates Protocol V2 message serialization, event streaming, and error handling.

• [ ] Review .claude/docs/protocol-v2.md and .claude/docs/api-v2-patterns.md to identify testable Protocol V2 behaviors
• [ ] Create ci/protocol-v2.runsettings (alongside existing ci/ci.runsettings) for Protocol V2 test configuration
• [ ] Add test project(s) under an appropriate location (e.g., src/KurrentDB.Tests.ProtocolV2/) covering message validation, serialization roundtrips, and streaming scenarios
• [ ] Integrate new tests into .github/workflows/build-reusable.yml and .github/workflows/build-ubuntu-22.04.yml

Expand .claude/agents/ documentation with Testing Agent guidelines

The .claude/ directory has architect-review.md, but the file structure suggests an agent-based development workflow is in place. The .claude/docs/testing.md exists but there's no corresponding agent guide for how contributors should structure tests, when to involve testing patterns, or validation criteria. This would help new contributors understand the testing philosophy and reduce review cycles.

• [ ] Review existing .claude/docs/testing.md to understand current testing patterns and conventions
• [ ] Create .claude/agents/testing-agent.md documenting: when to write unit vs. integration tests, Protocol V2 test requirements, and test naming conventions
• [ ] Reference testing patterns from ci/ci.runsettings and existing test configurations
• [ ] Link from CONTRIBUTING.md to this new agent guide for new contributors

Add GitHub Action workflow for documentation link validation on PRs

The docs directory has custom markdown plugins for link checking (.vuepress/markdown/linkCheck/) and link replacement (.vuepress/markdown/replaceLink/), but there's no CI workflow preventing broken links from merging. With frequent documentation updates and versioning (evident from .vuepress/lib/versioning.ts), this prevents documentation rot and improves user experience.

• [ ] Create .github/workflows/validate-docs-links.yml that runs markdown-it link validation on docs/ changes
• [ ] Configure workflow to use existing .vuepress/markdown/linkCheck plugin logic
• [ ] Set workflow to trigger on pull_request targeting docs/** paths
• [ ] Add workflow status badge and documentation to CONTRIBUTING.md

• Write integration tests for the gRPC Protocol v2 API surfaces documented in .claude/docs/protocol-v2.md; the protocol is formally specified but likely under-tested at boundary conditions
• Audit and document the event stream subscription patterns in .claude/docs/patterns-and-conventions.md with concrete code examples; contributors need runnable patterns, not just abstract guidance
• Add ARM64-specific performance benchmarks in ci/ (currently ci.rsp and ci.runsettings lack ARM tuning); build-ubuntu-20.04-arm64.yml exists but no visible benchmark harness

• High · Outdated Babel Dependencies — docs/package.json - devDependencies. The Babel CLI and core packages (@babel/cli@^7.24.8, @babel/core@^7.24.9) are using caret versioning which allows patch and minor updates. These packages have known vulnerabilities in older versions. The caret range may pull in versions with unpatched security issues. Fix: Review and pin specific versions of @babel packages after security audit. Consider using npm audit to identify and fix known vulnerabilities. Use exact versions (remove ^) for security-sensitive dependencies.
• High · Outdated ESLint Configuration — docs/package.json - devDependencies. The ESLint package (^8.57.0) uses caret versioning. ESLint plugins like eslint-config-vuepress may have security vulnerabilities. Additionally, the package.json allows flexibility in version ranges that could introduce vulnerable versions. Fix: Pin ESLint and related linting packages to specific versions. Run 'npm audit' and address any flagged vulnerabilities. Consider using npm ci instead of npm install in CI/CD pipelines.
• High · Unencrypted Certificate Generation in Docker Compose — docker-compose.yml - cert-gen service. The docker-compose.yml file generates TLS certificates with world-readable permissions (chmod 666) in the cert-gen service. This exposes private keys that should be restricted to specific users. The certificates are then used for esdb-node services with potentially weak permission controls. Fix: Change permissions to 600 or 640 for certificate files. Restrict certificate directory access to specific UIDs/GIDs. Use 'user: root' temporarily only for chmod operations, then revert. Consider using a proper secrets management solution instead of file-based certificates.
• High · Incomplete Docker Compose Configuration Exposure — docker-compose.yml - esdb-node1 service. The docker-compose.yml snippet shows truncated environment variables and command definitions (e.g., 'K' is incomplete). This suggests the full configuration may contain hardcoded secrets, credentials, or sensitive configuration values that are not visible in the provided snippet but likely exist in the repository. Fix: Review the complete docker-compose.yml for hardcoded credentials. Use environment variable files (.env) with proper .gitignore rules. Never commit secrets to the repository. Use Docker secrets or external secret management for production deployments.
• Medium · Package Manager Lock File Not Enforced — docs/package.json - preinstall script. The package.json specifies 'packageManager: pnpm@10.13.1' but relies on 'npx only-allow pnpm' preinstall script. This is weaker than using package-lock.json or pnpm-lock.yaml for reproducible builds. The preinstall script may not prevent all package manager switching scenarios. Fix: Ensure pnpm-lock.yaml is committed to version control and not in .gitignore. Add CI/CD checks to verify lockfile integrity. Consider adding additional validation in CI to verify only pnpm is used.
• Medium · Generic Security Contact Information — SECURITY.md. The SECURITY.md file provides only a generic URL (https://www.kurrent.io/security#security) without specific security contact details, PGP keys, or vulnerability disclosure timeline expectations. This makes it harder for security researchers to responsibly report vulnerabilities. Fix: Enhance SECURITY.md with: specific security contact email, PGP public key, expected response timeframe, vulnerability disclosure policy, and bug bounty information if applicable. Follow the standard security.txt format.
• Medium · Vuepress Theme with Unspecified Security Patches — docs/package.json - dependencies. The vuepress-theme-hope package (^2.0.0-rc.71) is a release candidate version. Release candidates may not have stable security patches and should not be used in production. The caret allows minor version updates that could introduce breaking changes or security issues. Fix: Upgrade to the latest stable release of vuepress-theme-hope. Avoid using pre-release versions in production. Pin to exact versions after verification: '2.0.0' instead of '^2.0.0-rc.71'.
• Medium · Dockerfile — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.