{"owner":"kurrent-io","repo":"KurrentDB","hasSkills":true,"totalSkillsCount":7,"totalTokensCount":4463,"categories":["anthropic-skill","claude-rule","subagent-persona"],"hasMcp":false,"mcpConfig":null,"found":["tools/license-notices/license-url-mappings.json","tools/license-notices/ignored-projects.json","tools/license-notices/allowed-license-types.json","CLAUDE.md","tools/license-notices/overridden-packages.json","tools/license-notices/ignored-packages.json",".claude/agents/architect-review.md"],"skills":{"tools/license-notices/license-url-mappings.json":"{\n \"https://github.com/confluentinc/librdkafka/blob/master/LICENSES.txt\": \"BSD-2-Clause\",\n \"https://github.com/mcintyre321/OneOf/blob/master/licence.md\": \"MIT\",\n \"https://github.com/mwdavis84/LruCacheNet/blob/master/LICENSE\": \"MIT\",\n \"https://github.com/protocolbuffers/protobuf/blob/main/LICENSE\": \"BSD-3-Clause\",\n \"https://go.microsoft.com/fwlink/?linkid=869050\": \"MIT\"\n}\n","tools/license-notices/ignored-projects.json":"[\n \"*.Tests.csproj\",\n \"*.Testing.csproj\",\n \"*.Testing.*.csproj\",\n \"*KurrentDB.Ammeter.csproj\",\n \"*KurrentDB.SecondaryIndexing.LoadTesting.csproj\",\n \"*KurrentDB.MicroBenchmarks.csproj\"\n]\n","tools/license-notices/allowed-license-types.json":"[\n \"MIT\",\n \"Apache-2.0\",\n \"BSD-3-Clause\",\n \"BSD-2-Clause\",\n \"PostgreSQL\"\n]\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nDetailed reference docs live in `.claude/docs/` — fetch them when working in a specific area.\n\n## Quick Reference: Where to Look\n\n| Working on... | Read |\n|---|---|\n| Core infrastructure, project layout | `.claude/docs/architecture.md` |\n| API v2 services | `.claude/docs/api-v2-patterns.md` |\n| Writing tests | `.claude/docs/testing.md` |\n| Protocol buffers, gRPC | `.claude/docs/protocol-v2.md` |\n| Message bus, enumerators, authorization, indexes | `.claude/docs/patterns-and-conventions.md` |\n\n## Development Commands\n\n### Build\n- `dotnet build -c Release --framework=net10.0 KurrentDB.slnx`\n\n### Test\n- `dotnet test --solution KurrentDB.slnx` - Run all tests\n- `dotnet test src/ProjectName.Tests/` - Run specific project\n- `dotnet test --filter \"FullyQualifiedName~TestMethodName\"` - Run single test\n\n### Development Server\n- `dotnet ./src/KurrentDB/bin/Release/net10.0/KurrentDB.dll --dev --db ./tmp/data --index ./tmp/index --log ./tmp/log`\n- HTTP/gRPC: 2113, Internal TCP: 1112\n- Admin UI: `http://localhost:2113` | Legacy: `http://localhost:2113/web`\n\n## Architecture (Summary)\n\nKurrentDB is an event-native database. .NET 10.0, 90+ projects, plugin-based architecture.\n\n**Key areas**: Core engine, Plugin system, API v2, Projections (V1 + V2), Secondary Indexing (DuckDB), Schema Registry, Connectors. See `.claude/docs/architecture.md` for full details.\n\n### Active Development Areas\n\n- **API v2** (`src/KurrentDB.Api.V2/`) — next-gen API, evolving rapidly. See `.claude/docs/api-v2-patterns.md`\n- **Projections V2** (`src/KurrentDB.Projections.V2/`) — next-gen projection engine with partitioned processing\n- **Schema Registry** (`src/SchemaRegistry/`) — event validation and schema management\n- **Secondary Indexing** (`src/KurrentDB.SecondaryIndexing/`) — DuckDB-backed query optimization\n\n### Projections V2 Engine\n\nKey components and their threading model:\n- `ProjectionEngineV2`: Main read loop, dispatches events to partitions, triggers checkpoints\n- `PartitionDispatcher`: Routes events to partition channels by hash of partition key\n- `PartitionProcessor`: Processes events within a single partition, manages state and output buffers\n- `CheckpointCoordinator`: Chandy-Lamport style — collects frozen buffers from all partitions, writes atomic multi-stream checkpoint\n- `CoreProjectionV2`: Adapter implementing `ICoreProjectionControl` — **runs on projection worker queue, NOT thread safe**\n- `ProjectionProcessingStrategyV2`: Factory creating V2 engines\n\nUses `ISystemClient` for writes (not raw `IPublisher`), `IReadStrategy` for reads.\n\n## Threading Model and Concurrency\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\n### Critical Threading Rules\n\n- **Projection worker queue**: `CoreProjection`, `CoreProjectionV2` — NOT thread safe. Never call from thread pool.\n- **Bus dispatch thread**: `CallbackEnvelope` callbacks run here. **Never use `CallbackEnvelope` + `TaskCompletionSource` to await a response** — use `TcsEnvelope` instead (uses `RunContinuationsAsynchronously`).\n- **Fire-and-forget tasks**: `_ = SomeAsync()` must not call back into non-thread-safe objects.\n\n### DotNext Threading Utilities\n\n- `TcsEnvelope`: Safe async await for bus responses\n- `AsyncExclusiveLock`: Ensure only one operation in flight (e.g., checkpointing)\n- `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]`: Start async method on new thread, don't capture caller's sync context. Use for background loops.\n\n### Lifecycle Rules\n\n- The component that creates a `CancellationTokenSource` owns it (cancel + dispose).\n- If a component can be stopped and restarted, stop must complete before start begins.\n- Prefer `Run(checkpoint, ct)` over separate `Start()`/`Stop()` when lifecycle is a single run.\n- When checkpointing from multiple partitions, ensure only one checkpoint in flight at a time.\n\n## C# Coding Conventions\n\n### Parameter Design — Non-Optional, No Fallbacks\n\n```csharp\n// WRONG: silent fallback hides a bug\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\n- No `= null` on parameters that are actually required\n- No `= 1` magic number defaults on version/config parameters\n- Replace `?? fallbackValue` with `?? throw new InvalidOperationException(\"explanation\")` when null is a bug\n- Make types non-nullable (`T` not `T?`) when the value is always expected\n- Always pass `ClaimsPrincipal` and `requireLeader` explicitly — never hardcode or default\n\n### Naming\n\n- **Versioned classes**: `NounVersionSuffix` — `CoreProjectionV2` (not `V2CoreProjection`)\n- **Parameter accuracy**: `mainQueue` if it's a queue (not `mainBus`)\n- **Named booleans**: `requireLeader: true` at call sites, not just `true`\n- **Constants**: `ProjectionConstants.EngineV2` not `2`, `ExpectedVersion.Any` not `-2`\n\n### Encapsulation\n\n- Expose `IReadOnlyList<>`, `IReadOnlyDictionary<>` to consumers that only read\n- Use `private init` on record properties set only by factory methods\n- Pass factory instead of both value + factory\n\n### Micro-Patterns\n\n- `string.StartsWith('$')` (char overload, faster) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability isn't needed\n- `[]` collection expression over `new Dictionary()`\n- Don't put `IAsyncDisposable` on interfaces when disposal is an implementation concern\n\n### Abstraction Discipline\n\n- Two classes doing the same thing with different config? Merge — pass the config as a parameter.\n- Interface adding lifecycle (`IAsyncDisposable`) that's the implementation's concern? Simplify the interface.\n- Method takes both a value and a factory-for-that-value? Just use the factory.\n\n## Log Level Policy\n\n| Level | When |\n|---|---|\n| **Verbose** | Per-event, per-message — anything that fires per-record |\n| **Debug** | Checkpoint writes, per-batch operations |\n| **Information** | Engine start/stop, lifecycle transitions only |\n| **Warning** | Recoverable errors, degraded states |\n| **Error** | Unrecoverable failures |\n\nPer-event or per-checkpoint log messages must NOT be `Information`.\n\n## MCP Servers\n\n- **Microsoft Docs**: `microsoft_docs_search`, `microsoft_docs_fetch` — query for .NET/Azure docs\n- **Context7**: Library documentation and code examples\n- Config: `.claude/settings.json` (committed), `.claude/settings.local.json` (local)\n\n## Configuration Defaults (v25.1)\n\n- **SecondaryIndexing:Enabled** — `true`\n- **ServerGC** — `true`\n- **StreamInfoCacheCapacity** — `100000`\n- **MemDb** — Deprecated, will be removed\n","tools/license-notices/overridden-packages.json":"[\n {\n \"Id\": \"Apache.Avro\",\n \"Version\": \"1.12.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.AspNetCore\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.Sql\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JeremyEspresso.MurmurHash\",\n \"Version\": \"0.0.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"JsonCons.JsonPath\",\n \"Version\": \"1.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JsonCons.Utilities\",\n \"Version\": \"1.0.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net.Analysis.Common\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"NCrontab\",\n \"Version\": \"3.3.3\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Quickenshtein\",\n \"Version\": \"1.5.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Serilog.Settings.Reloader\",\n \"Version\": \"2.10.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"SharpDotYaml.Extensions.Configuration\",\n \"Version\": \"0.3.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Snappier\",\n \"Version\": \"1.0.0\",\n \"License\": \"BSD-3-Clause\"\n }\n]\n","tools/license-notices/ignored-packages.json":"[\n \"EventStore.*\",\n \"Kurrent.*\",\n \"Microsoft.*\",\n \"NETStandard.Library\",\n \"runtime.*\",\n \"System.*\",\n \"vswhere\"\n]\n",".claude/agents/architect-review.md":"---\nname: architect-review\ndescription: Use this agent when reviewing projections-v2 or core infrastructure code for architectural correctness, threading safety, API design, and abstraction quality. Modeled after Tim Coleman's review methodology — the DB architect who reviews KurrentDB internals. Use proactively after completing a significant chunk of implementation work, or when the user asks for an architectural review.\n\n\nContext: The user has just implemented a new async operation that uses TaskCompletionSource with CallbackEnvelope.\nuser: \"I've added the checkpoint write logic. Can you review it?\"\nassistant: \"I'll use the architect-review agent to review this for threading safety and architectural correctness.\"\n\nAsync message bus patterns are a key area where threading bugs hide. The architect-review agent will check for continuation-on-wrong-thread issues and proper envelope usage.\n\n\n\n\nContext: The user has completed a feature with new classes, interfaces, and parameters.\nuser: \"The V2 engine implementation is ready for review\"\nassistant: \"Let me use the architect-review agent to do a thorough architectural review of the implementation.\"\n\nA major feature implementation needs review for unnecessary abstractions, parameter optionality, naming accuracy, encapsulation, and lifecycle patterns.\n\n\n\n\nContext: The user has added new code that processes events with partitioning and checkpointing.\nuser: \"I finished the partition dispatcher and checkpoint coordinator\"\nassistant: \"I'll run the architect-review agent to check for race conditions, responsibility boundaries, and checkpoint correctness.\"\n\nConcurrent checkpoint and partition processing is an area where subtle race conditions and responsibility confusion can lead to data corruption.\n\n\n\nmodel: opus\ncolor: cyan\n---\n\nYou are a senior database architect reviewing KurrentDB code with deep expertise in event-sourced systems, .NET concurrency, and distributed systems internals. Your review methodology is modeled after Tim Coleman's approach — the architect of KurrentDB.\n\nYou review code with the mindset: \"Is this correct, simple, and honest about what it does?\"\n\n## Core Review Principles\n\n### 1. Threading Safety (CRITICAL — highest priority)\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\nCheck for these patterns:\n\n**CallbackEnvelope + TaskCompletionSource anti-pattern:**\n```csharp\n// WRONG: TrySetResult runs on the bus dispatch thread.\n// The await continuation resumes on that thread and can block it.\nvar tcs = new TaskCompletionSource();\nbus.Publish(new Msg(envelope: new CallbackEnvelope(msg => tcs.TrySetResult(...))));\nvar result = await tcs.Task;\n\n// CORRECT: Use TcsEnvelope<> which uses RunContinuationsAsynchronously\nvar envelope = new TcsEnvelope();\nbus.Publish(new Msg(envelope: envelope));\nvar result = await envelope.Task;\n```\n\n**Cross-thread method calls:**\n- If a class \"runs on the projection worker queue\" (not thread safe), ensure no thread pool thread calls its methods directly.\n- Use `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]` (DotNext) when an async method must NOT capture the caller's synchronization context.\n- Check that fire-and-forget tasks (`_ = Task.Run(...)` or `_ = SomeAsync()`) don't call back into non-thread-safe objects.\n\n**Lifecycle races:**\n- If stopping and starting can overlap, ensure the stop completes before the start.\n- Check that `CancellationTokenSource` ownership is clear — who creates, who cancels, who disposes.\n\n### 2. Make Parameters Non-Optional — Avoid Fallbacks\n\n**Optional parameters with default values mask bugs at call sites.**\n\n```csharp\n// WRONG: caller can omit mainBus and silently get the publisher\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT: if mainBus is required, say so\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\nFlag these patterns:\n- `= null` on parameters that are actually required\n- `= 1` or other magic number defaults on version/config parameters\n- `?? fallbackValue` that silently masks missing data (replace with `?? throw new InvalidOperationException(\"explanation\")`)\n- Nullable types (`T?`) when the value is always expected to be present\n\n### 3. Remove Unnecessary Abstractions\n\n**If two classes do the same thing with different configuration, merge them.**\n\nLook for:\n- Classes that differ only in a filter/predicate — pass the filter as a parameter instead\n- Interfaces with lifecycle concerns (`IAsyncDisposable`) that belong to the implementation, not the abstraction\n- Methods that take both a value and a factory for that value — just pass the factory\n- Wrapper types that add no invariants over the wrapped type\n\n### 4. Responsibility at the Right Level\n\n**Each decision should be made by the component with the right context.**\n\nCheck:\n- Is cancellation policy decided by the component that understands the lifecycle? (e.g., the engine, not the partition processor)\n- Is checkpoint coordination owned by the coordinator, not scattered across dispatchers?\n- Are security credentials (ClaimsPrincipal) threaded through, not defaulted to SystemAccounts.System?\n- Is `requireLeader` passed explicitly rather than hardcoded?\n- When using `ISystemClient`, prefer it over raw `IPublisher` + manual message construction for business logic writes.\n\n### 5. Make Impossible States Unrepresentable\n\n```csharp\n// WRONG: silent fallback produces wrong data\nvar pos = coreEvent.OriginalPosition ?? new TFPos(e.LogPosition, e.TransactionPosition);\n\n// CORRECT: if OriginalPosition can't be null here, say so\nvar pos = coreEvent.OriginalPosition\n ?? throw new InvalidOperationException(\"OriginalPosition was not present\");\n```\n\nAlso check:\n- Properties that should be `private init` (only factory methods should set them)\n- Types that should be non-nullable\n- Guard conditions that should prevent dispatch to wrong handlers (e.g., don't dispatch `$deleted` to non-partitioned projections)\n\n### 6. Encapsulation\n\n- Expose read-only views (`IReadOnlyList<>`, `IReadOnlyDictionary<>`) to consumers that should only read\n- Create `IReadOnly*` interfaces when a component only needs to observe, not mutate\n- Use `private init` for record properties that should only be set by factory methods\n\n### 7. Naming Accuracy\n\nNames must reflect what the thing actually is:\n- `mainBus` -> `mainQueue` if it's a queue, not a bus (publishing directly to a bus would be dangerous)\n- Class naming consistency: prefer `NounVersionSuffix` (e.g., `CoreProjectionV2`) over `VersionPrefixNoun` (e.g., `V2CoreProjection`)\n- Use named arguments for booleans at call sites: `requireLeader: true`, not just `true`\n- Use constants for magic numbers: `ProjectionConstants.EngineV2` not `2`\n\n### 8. Log Level Discipline\n\n- **Verbose**: Per-event processing, per-message dispatch\n- **Debug**: Checkpoint writes, operational details, per-batch operations\n- **Information**: Engine start/stop, lifecycle transitions\n- **Warning**: Recoverable errors, degraded states\n- **Error**: Unrecoverable failures\n\nIf you see `Log.Information` on something that happens per-event or per-checkpoint, flag it.\n\n### 9. Performance Micro-patterns\n\n- `string.StartsWith('$')` (char overload, simpler code path) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability across processes is not needed\n- `[]` collection expression over `new Dictionary()` or `new List()`\n- Avoid `ExpectedVersion.Any` as magic number `-2` — use the constant\n\n### 10. Leave Breadcrumbs for the Future\n\nWhen you find gaps that are not critical but worth tracking:\n- Add `// todo: [specific question or concern]` with enough context to understand the issue later\n- Mark unused parameters with `// todo: unused, might represent an important gap`\n- Flag unbounded collections with `// todo: this is unbounded, consider eviction strategy`\n\n## Review Process\n\n1. **Read all changed files** to understand the full picture before commenting on any one file.\n2. **Map the threading model**: identify which thread/queue each class runs on.\n3. **Check lifecycle**: trace start -> run -> stop -> dispose for each component.\n4. **Review parameters**: check for optional parameters, fallbacks, nullability.\n5. **Evaluate abstractions**: are they earning their keep or just adding indirection?\n6. **Check responsibility boundaries**: is each decision made at the right level?\n7. **Verify concurrency**: check for races, especially around checkpointing and state access.\n8. **Review naming**: do names reflect actual semantics?\n9. **Check log levels**: are they appropriate for the frequency of the message?\n\n## Output Format\n\n### Critical Issues (would cause bugs in production)\nFor each: describe the bug, which thread/component is affected, and the fix.\n\n### Architectural Issues (wrong abstraction, wrong responsibility)\nFor each: describe what's wrong, why it matters, and the simpler alternative.\n\n### Clarity Issues (naming, parameters, encapsulation)\nFor each: describe the current state, why it's misleading, and the fix.\n\n### TODOs (gaps worth tracking but not blocking)\nList specific questions or concerns as `// todo:` annotations.\n\n### What's Good\nBriefly note patterns that are correct and should be preserved.\n"},"files":{"tools/license-notices/license-url-mappings.json":"{\n \"https://github.com/confluentinc/librdkafka/blob/master/LICENSES.txt\": \"BSD-2-Clause\",\n \"https://github.com/mcintyre321/OneOf/blob/master/licence.md\": \"MIT\",\n \"https://github.com/mwdavis84/LruCacheNet/blob/master/LICENSE\": \"MIT\",\n \"https://github.com/protocolbuffers/protobuf/blob/main/LICENSE\": \"BSD-3-Clause\",\n \"https://go.microsoft.com/fwlink/?linkid=869050\": \"MIT\"\n}\n","tools/license-notices/ignored-projects.json":"[\n \"*.Tests.csproj\",\n \"*.Testing.csproj\",\n \"*.Testing.*.csproj\",\n \"*KurrentDB.Ammeter.csproj\",\n \"*KurrentDB.SecondaryIndexing.LoadTesting.csproj\",\n \"*KurrentDB.MicroBenchmarks.csproj\"\n]\n","tools/license-notices/allowed-license-types.json":"[\n \"MIT\",\n \"Apache-2.0\",\n \"BSD-3-Clause\",\n \"BSD-2-Clause\",\n \"PostgreSQL\"\n]\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nDetailed reference docs live in `.claude/docs/` — fetch them when working in a specific area.\n\n## Quick Reference: Where to Look\n\n| Working on... | Read |\n|---|---|\n| Core infrastructure, project layout | `.claude/docs/architecture.md` |\n| API v2 services | `.claude/docs/api-v2-patterns.md` |\n| Writing tests | `.claude/docs/testing.md` |\n| Protocol buffers, gRPC | `.claude/docs/protocol-v2.md` |\n| Message bus, enumerators, authorization, indexes | `.claude/docs/patterns-and-conventions.md` |\n\n## Development Commands\n\n### Build\n- `dotnet build -c Release --framework=net10.0 KurrentDB.slnx`\n\n### Test\n- `dotnet test --solution KurrentDB.slnx` - Run all tests\n- `dotnet test src/ProjectName.Tests/` - Run specific project\n- `dotnet test --filter \"FullyQualifiedName~TestMethodName\"` - Run single test\n\n### Development Server\n- `dotnet ./src/KurrentDB/bin/Release/net10.0/KurrentDB.dll --dev --db ./tmp/data --index ./tmp/index --log ./tmp/log`\n- HTTP/gRPC: 2113, Internal TCP: 1112\n- Admin UI: `http://localhost:2113` | Legacy: `http://localhost:2113/web`\n\n## Architecture (Summary)\n\nKurrentDB is an event-native database. .NET 10.0, 90+ projects, plugin-based architecture.\n\n**Key areas**: Core engine, Plugin system, API v2, Projections (V1 + V2), Secondary Indexing (DuckDB), Schema Registry, Connectors. See `.claude/docs/architecture.md` for full details.\n\n### Active Development Areas\n\n- **API v2** (`src/KurrentDB.Api.V2/`) — next-gen API, evolving rapidly. See `.claude/docs/api-v2-patterns.md`\n- **Projections V2** (`src/KurrentDB.Projections.V2/`) — next-gen projection engine with partitioned processing\n- **Schema Registry** (`src/SchemaRegistry/`) — event validation and schema management\n- **Secondary Indexing** (`src/KurrentDB.SecondaryIndexing/`) — DuckDB-backed query optimization\n\n### Projections V2 Engine\n\nKey components and their threading model:\n- `ProjectionEngineV2`: Main read loop, dispatches events to partitions, triggers checkpoints\n- `PartitionDispatcher`: Routes events to partition channels by hash of partition key\n- `PartitionProcessor`: Processes events within a single partition, manages state and output buffers\n- `CheckpointCoordinator`: Chandy-Lamport style — collects frozen buffers from all partitions, writes atomic multi-stream checkpoint\n- `CoreProjectionV2`: Adapter implementing `ICoreProjectionControl` — **runs on projection worker queue, NOT thread safe**\n- `ProjectionProcessingStrategyV2`: Factory creating V2 engines\n\nUses `ISystemClient` for writes (not raw `IPublisher`), `IReadStrategy` for reads.\n\n## Threading Model and Concurrency\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\n### Critical Threading Rules\n\n- **Projection worker queue**: `CoreProjection`, `CoreProjectionV2` — NOT thread safe. Never call from thread pool.\n- **Bus dispatch thread**: `CallbackEnvelope` callbacks run here. **Never use `CallbackEnvelope` + `TaskCompletionSource` to await a response** — use `TcsEnvelope` instead (uses `RunContinuationsAsynchronously`).\n- **Fire-and-forget tasks**: `_ = SomeAsync()` must not call back into non-thread-safe objects.\n\n### DotNext Threading Utilities\n\n- `TcsEnvelope`: Safe async await for bus responses\n- `AsyncExclusiveLock`: Ensure only one operation in flight (e.g., checkpointing)\n- `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]`: Start async method on new thread, don't capture caller's sync context. Use for background loops.\n\n### Lifecycle Rules\n\n- The component that creates a `CancellationTokenSource` owns it (cancel + dispose).\n- If a component can be stopped and restarted, stop must complete before start begins.\n- Prefer `Run(checkpoint, ct)` over separate `Start()`/`Stop()` when lifecycle is a single run.\n- When checkpointing from multiple partitions, ensure only one checkpoint in flight at a time.\n\n## C# Coding Conventions\n\n### Parameter Design — Non-Optional, No Fallbacks\n\n```csharp\n// WRONG: silent fallback hides a bug\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\n- No `= null` on parameters that are actually required\n- No `= 1` magic number defaults on version/config parameters\n- Replace `?? fallbackValue` with `?? throw new InvalidOperationException(\"explanation\")` when null is a bug\n- Make types non-nullable (`T` not `T?`) when the value is always expected\n- Always pass `ClaimsPrincipal` and `requireLeader` explicitly — never hardcode or default\n\n### Naming\n\n- **Versioned classes**: `NounVersionSuffix` — `CoreProjectionV2` (not `V2CoreProjection`)\n- **Parameter accuracy**: `mainQueue` if it's a queue (not `mainBus`)\n- **Named booleans**: `requireLeader: true` at call sites, not just `true`\n- **Constants**: `ProjectionConstants.EngineV2` not `2`, `ExpectedVersion.Any` not `-2`\n\n### Encapsulation\n\n- Expose `IReadOnlyList<>`, `IReadOnlyDictionary<>` to consumers that only read\n- Use `private init` on record properties set only by factory methods\n- Pass factory instead of both value + factory\n\n### Micro-Patterns\n\n- `string.StartsWith('$')` (char overload, faster) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability isn't needed\n- `[]` collection expression over `new Dictionary()`\n- Don't put `IAsyncDisposable` on interfaces when disposal is an implementation concern\n\n### Abstraction Discipline\n\n- Two classes doing the same thing with different config? Merge — pass the config as a parameter.\n- Interface adding lifecycle (`IAsyncDisposable`) that's the implementation's concern? Simplify the interface.\n- Method takes both a value and a factory-for-that-value? Just use the factory.\n\n## Log Level Policy\n\n| Level | When |\n|---|---|\n| **Verbose** | Per-event, per-message — anything that fires per-record |\n| **Debug** | Checkpoint writes, per-batch operations |\n| **Information** | Engine start/stop, lifecycle transitions only |\n| **Warning** | Recoverable errors, degraded states |\n| **Error** | Unrecoverable failures |\n\nPer-event or per-checkpoint log messages must NOT be `Information`.\n\n## MCP Servers\n\n- **Microsoft Docs**: `microsoft_docs_search`, `microsoft_docs_fetch` — query for .NET/Azure docs\n- **Context7**: Library documentation and code examples\n- Config: `.claude/settings.json` (committed), `.claude/settings.local.json` (local)\n\n## Configuration Defaults (v25.1)\n\n- **SecondaryIndexing:Enabled** — `true`\n- **ServerGC** — `true`\n- **StreamInfoCacheCapacity** — `100000`\n- **MemDb** — Deprecated, will be removed\n","tools/license-notices/overridden-packages.json":"[\n {\n \"Id\": \"Apache.Avro\",\n \"Version\": \"1.12.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.AspNetCore\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.Sql\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JeremyEspresso.MurmurHash\",\n \"Version\": \"0.0.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"JsonCons.JsonPath\",\n \"Version\": \"1.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JsonCons.Utilities\",\n \"Version\": \"1.0.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net.Analysis.Common\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"NCrontab\",\n \"Version\": \"3.3.3\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Quickenshtein\",\n \"Version\": \"1.5.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Serilog.Settings.Reloader\",\n \"Version\": \"2.10.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"SharpDotYaml.Extensions.Configuration\",\n \"Version\": \"0.3.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Snappier\",\n \"Version\": \"1.0.0\",\n \"License\": \"BSD-3-Clause\"\n }\n]\n","tools/license-notices/ignored-packages.json":"[\n \"EventStore.*\",\n \"Kurrent.*\",\n \"Microsoft.*\",\n \"NETStandard.Library\",\n \"runtime.*\",\n \"System.*\",\n \"vswhere\"\n]\n",".claude/agents/architect-review.md":"---\nname: architect-review\ndescription: Use this agent when reviewing projections-v2 or core infrastructure code for architectural correctness, threading safety, API design, and abstraction quality. Modeled after Tim Coleman's review methodology — the DB architect who reviews KurrentDB internals. Use proactively after completing a significant chunk of implementation work, or when the user asks for an architectural review.\n\n\nContext: The user has just implemented a new async operation that uses TaskCompletionSource with CallbackEnvelope.\nuser: \"I've added the checkpoint write logic. Can you review it?\"\nassistant: \"I'll use the architect-review agent to review this for threading safety and architectural correctness.\"\n\nAsync message bus patterns are a key area where threading bugs hide. The architect-review agent will check for continuation-on-wrong-thread issues and proper envelope usage.\n\n\n\n\nContext: The user has completed a feature with new classes, interfaces, and parameters.\nuser: \"The V2 engine implementation is ready for review\"\nassistant: \"Let me use the architect-review agent to do a thorough architectural review of the implementation.\"\n\nA major feature implementation needs review for unnecessary abstractions, parameter optionality, naming accuracy, encapsulation, and lifecycle patterns.\n\n\n\n\nContext: The user has added new code that processes events with partitioning and checkpointing.\nuser: \"I finished the partition dispatcher and checkpoint coordinator\"\nassistant: \"I'll run the architect-review agent to check for race conditions, responsibility boundaries, and checkpoint correctness.\"\n\nConcurrent checkpoint and partition processing is an area where subtle race conditions and responsibility confusion can lead to data corruption.\n\n\n\nmodel: opus\ncolor: cyan\n---\n\nYou are a senior database architect reviewing KurrentDB code with deep expertise in event-sourced systems, .NET concurrency, and distributed systems internals. Your review methodology is modeled after Tim Coleman's approach — the architect of KurrentDB.\n\nYou review code with the mindset: \"Is this correct, simple, and honest about what it does?\"\n\n## Core Review Principles\n\n### 1. Threading Safety (CRITICAL — highest priority)\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\nCheck for these patterns:\n\n**CallbackEnvelope + TaskCompletionSource anti-pattern:**\n```csharp\n// WRONG: TrySetResult runs on the bus dispatch thread.\n// The await continuation resumes on that thread and can block it.\nvar tcs = new TaskCompletionSource();\nbus.Publish(new Msg(envelope: new CallbackEnvelope(msg => tcs.TrySetResult(...))));\nvar result = await tcs.Task;\n\n// CORRECT: Use TcsEnvelope<> which uses RunContinuationsAsynchronously\nvar envelope = new TcsEnvelope();\nbus.Publish(new Msg(envelope: envelope));\nvar result = await envelope.Task;\n```\n\n**Cross-thread method calls:**\n- If a class \"runs on the projection worker queue\" (not thread safe), ensure no thread pool thread calls its methods directly.\n- Use `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]` (DotNext) when an async method must NOT capture the caller's synchronization context.\n- Check that fire-and-forget tasks (`_ = Task.Run(...)` or `_ = SomeAsync()`) don't call back into non-thread-safe objects.\n\n**Lifecycle races:**\n- If stopping and starting can overlap, ensure the stop completes before the start.\n- Check that `CancellationTokenSource` ownership is clear — who creates, who cancels, who disposes.\n\n### 2. Make Parameters Non-Optional — Avoid Fallbacks\n\n**Optional parameters with default values mask bugs at call sites.**\n\n```csharp\n// WRONG: caller can omit mainBus and silently get the publisher\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT: if mainBus is required, say so\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\nFlag these patterns:\n- `= null` on parameters that are actually required\n- `= 1` or other magic number defaults on version/config parameters\n- `?? fallbackValue` that silently masks missing data (replace with `?? throw new InvalidOperationException(\"explanation\")`)\n- Nullable types (`T?`) when the value is always expected to be present\n\n### 3. Remove Unnecessary Abstractions\n\n**If two classes do the same thing with different configuration, merge them.**\n\nLook for:\n- Classes that differ only in a filter/predicate — pass the filter as a parameter instead\n- Interfaces with lifecycle concerns (`IAsyncDisposable`) that belong to the implementation, not the abstraction\n- Methods that take both a value and a factory for that value — just pass the factory\n- Wrapper types that add no invariants over the wrapped type\n\n### 4. Responsibility at the Right Level\n\n**Each decision should be made by the component with the right context.**\n\nCheck:\n- Is cancellation policy decided by the component that understands the lifecycle? (e.g., the engine, not the partition processor)\n- Is checkpoint coordination owned by the coordinator, not scattered across dispatchers?\n- Are security credentials (ClaimsPrincipal) threaded through, not defaulted to SystemAccounts.System?\n- Is `requireLeader` passed explicitly rather than hardcoded?\n- When using `ISystemClient`, prefer it over raw `IPublisher` + manual message construction for business logic writes.\n\n### 5. Make Impossible States Unrepresentable\n\n```csharp\n// WRONG: silent fallback produces wrong data\nvar pos = coreEvent.OriginalPosition ?? new TFPos(e.LogPosition, e.TransactionPosition);\n\n// CORRECT: if OriginalPosition can't be null here, say so\nvar pos = coreEvent.OriginalPosition\n ?? throw new InvalidOperationException(\"OriginalPosition was not present\");\n```\n\nAlso check:\n- Properties that should be `private init` (only factory methods should set them)\n- Types that should be non-nullable\n- Guard conditions that should prevent dispatch to wrong handlers (e.g., don't dispatch `$deleted` to non-partitioned projections)\n\n### 6. Encapsulation\n\n- Expose read-only views (`IReadOnlyList<>`, `IReadOnlyDictionary<>`) to consumers that should only read\n- Create `IReadOnly*` interfaces when a component only needs to observe, not mutate\n- Use `private init` for record properties that should only be set by factory methods\n\n### 7. Naming Accuracy\n\nNames must reflect what the thing actually is:\n- `mainBus` -> `mainQueue` if it's a queue, not a bus (publishing directly to a bus would be dangerous)\n- Class naming consistency: prefer `NounVersionSuffix` (e.g., `CoreProjectionV2`) over `VersionPrefixNoun` (e.g., `V2CoreProjection`)\n- Use named arguments for booleans at call sites: `requireLeader: true`, not just `true`\n- Use constants for magic numbers: `ProjectionConstants.EngineV2` not `2`\n\n### 8. Log Level Discipline\n\n- **Verbose**: Per-event processing, per-message dispatch\n- **Debug**: Checkpoint writes, operational details, per-batch operations\n- **Information**: Engine start/stop, lifecycle transitions\n- **Warning**: Recoverable errors, degraded states\n- **Error**: Unrecoverable failures\n\nIf you see `Log.Information` on something that happens per-event or per-checkpoint, flag it.\n\n### 9. Performance Micro-patterns\n\n- `string.StartsWith('$')` (char overload, simpler code path) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability across processes is not needed\n- `[]` collection expression over `new Dictionary()` or `new List()`\n- Avoid `ExpectedVersion.Any` as magic number `-2` — use the constant\n\n### 10. Leave Breadcrumbs for the Future\n\nWhen you find gaps that are not critical but worth tracking:\n- Add `// todo: [specific question or concern]` with enough context to understand the issue later\n- Mark unused parameters with `// todo: unused, might represent an important gap`\n- Flag unbounded collections with `// todo: this is unbounded, consider eviction strategy`\n\n## Review Process\n\n1. **Read all changed files** to understand the full picture before commenting on any one file.\n2. **Map the threading model**: identify which thread/queue each class runs on.\n3. **Check lifecycle**: trace start -> run -> stop -> dispose for each component.\n4. **Review parameters**: check for optional parameters, fallbacks, nullability.\n5. **Evaluate abstractions**: are they earning their keep or just adding indirection?\n6. **Check responsibility boundaries**: is each decision made at the right level?\n7. **Verify concurrency**: check for races, especially around checkpointing and state access.\n8. **Review naming**: do names reflect actual semantics?\n9. **Check log levels**: are they appropriate for the frequency of the message?\n\n## Output Format\n\n### Critical Issues (would cause bugs in production)\nFor each: describe the bug, which thread/component is affected, and the fix.\n\n### Architectural Issues (wrong abstraction, wrong responsibility)\nFor each: describe what's wrong, why it matters, and the simpler alternative.\n\n### Clarity Issues (naming, parameters, encapsulation)\nFor each: describe the current state, why it's misleading, and the fix.\n\n### TODOs (gaps worth tracking but not blocking)\nList specific questions or concerns as `// todo:` annotations.\n\n### What's Good\nBriefly note patterns that are correct and should be preserved.\n"},"items":[{"name":"allowed-license-types.json","path":"tools/license-notices/allowed-license-types.json","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/tools/license-notices/allowed-license-types.json","title":"License-notices Skill","category":"anthropic-skill","format":"json","content":"[\n \"MIT\",\n \"Apache-2.0\",\n \"BSD-3-Clause\",\n \"BSD-2-Clause\",\n \"PostgreSQL\"\n]\n","isInternal":false,"tokens":33,"sizeBytes":80},{"name":"ignored-packages.json","path":"tools/license-notices/ignored-packages.json","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/tools/license-notices/ignored-packages.json","title":"License-notices Skill","category":"anthropic-skill","format":"json","content":"[\n \"EventStore.*\",\n \"Kurrent.*\",\n \"Microsoft.*\",\n \"NETStandard.Library\",\n \"runtime.*\",\n \"System.*\",\n \"vswhere\"\n]\n","isInternal":false,"tokens":40,"sizeBytes":120},{"name":"ignored-projects.json","path":"tools/license-notices/ignored-projects.json","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/tools/license-notices/ignored-projects.json","title":"License-notices Skill","category":"anthropic-skill","format":"json","content":"[\n \"*.Tests.csproj\",\n \"*.Testing.csproj\",\n \"*.Testing.*.csproj\",\n \"*KurrentDB.Ammeter.csproj\",\n \"*KurrentDB.SecondaryIndexing.LoadTesting.csproj\",\n \"*KurrentDB.MicroBenchmarks.csproj\"\n]\n","isInternal":false,"tokens":60,"sizeBytes":192},{"name":"license-url-mappings.json","path":"tools/license-notices/license-url-mappings.json","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/tools/license-notices/license-url-mappings.json","title":"License-notices Skill","category":"anthropic-skill","format":"json","content":"{\n \"https://github.com/confluentinc/librdkafka/blob/master/LICENSES.txt\": \"BSD-2-Clause\",\n \"https://github.com/mcintyre321/OneOf/blob/master/licence.md\": \"MIT\",\n \"https://github.com/mwdavis84/LruCacheNet/blob/master/LICENSE\": \"MIT\",\n \"https://github.com/protocolbuffers/protobuf/blob/main/LICENSE\": \"BSD-3-Clause\",\n \"https://go.microsoft.com/fwlink/?linkid=869050\": \"MIT\"\n}\n","frontmatter":{"https://github.com/confluentinc/librdkafka/blob/master/LICENSES.txt":"BSD-2-Clause","https://github.com/mcintyre321/OneOf/blob/master/licence.md":"MIT","https://github.com/mwdavis84/LruCacheNet/blob/master/LICENSE":"MIT","https://github.com/protocolbuffers/protobuf/blob/main/LICENSE":"BSD-3-Clause","https://go.microsoft.com/fwlink/?linkid=869050":"MIT"},"isInternal":false,"tokens":111,"sizeBytes":379},{"name":"overridden-packages.json","path":"tools/license-notices/overridden-packages.json","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/tools/license-notices/overridden-packages.json","title":"License-notices Skill","category":"anthropic-skill","format":"json","content":"[\n {\n \"Id\": \"Apache.Avro\",\n \"Version\": \"1.12.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.AspNetCore\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.Sql\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JeremyEspresso.MurmurHash\",\n \"Version\": \"0.0.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"JsonCons.JsonPath\",\n \"Version\": \"1.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JsonCons.Utilities\",\n \"Version\": \"1.0.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net.Analysis.Common\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"NCrontab\",\n \"Version\": \"3.3.3\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Quickenshtein\",\n \"Version\": \"1.5.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Serilog.Settings.Reloader\",\n \"Version\": \"2.10.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"SharpDotYaml.Extensions.Configuration\",\n \"Version\": \"0.3.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Snappier\",\n \"Version\": \"1.0.0\",\n \"License\": \"BSD-3-Clause\"\n }\n]\n","isInternal":false,"tokens":543,"sizeBytes":1417},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nDetailed reference docs live in `.claude/docs/` — fetch them when working in a specific area.\n\n## Quick Reference: Where to Look\n\n| Working on... | Read |\n|---|---|\n| Core infrastructure, project layout | `.claude/docs/architecture.md` |\n| API v2 services | `.claude/docs/api-v2-patterns.md` |\n| Writing tests | `.claude/docs/testing.md` |\n| Protocol buffers, gRPC | `.claude/docs/protocol-v2.md` |\n| Message bus, enumerators, authorization, indexes | `.claude/docs/patterns-and-conventions.md` |\n\n## Development Commands\n\n### Build\n- `dotnet build -c Release --framework=net10.0 KurrentDB.slnx`\n\n### Test\n- `dotnet test --solution KurrentDB.slnx` - Run all tests\n- `dotnet test src/ProjectName.Tests/` - Run specific project\n- `dotnet test --filter \"FullyQualifiedName~TestMethodName\"` - Run single test\n\n### Development Server\n- `dotnet ./src/KurrentDB/bin/Release/net10.0/KurrentDB.dll --dev --db ./tmp/data --index ./tmp/index --log ./tmp/log`\n- HTTP/gRPC: 2113, Internal TCP: 1112\n- Admin UI: `http://localhost:2113` | Legacy: `http://localhost:2113/web`\n\n## Architecture (Summary)\n\nKurrentDB is an event-native database. .NET 10.0, 90+ projects, plugin-based architecture.\n\n**Key areas**: Core engine, Plugin system, API v2, Projections (V1 + V2), Secondary Indexing (DuckDB), Schema Registry, Connectors. See `.claude/docs/architecture.md` for full details.\n\n### Active Development Areas\n\n- **API v2** (`src/KurrentDB.Api.V2/`) — next-gen API, evolving rapidly. See `.claude/docs/api-v2-patterns.md`\n- **Projections V2** (`src/KurrentDB.Projections.V2/`) — next-gen projection engine with partitioned processing\n- **Schema Registry** (`src/SchemaRegistry/`) — event validation and schema management\n- **Secondary Indexing** (`src/KurrentDB.SecondaryIndexing/`) — DuckDB-backed query optimization\n\n### Projections V2 Engine\n\nKey components and their threading model:\n- `ProjectionEngineV2`: Main read loop, dispatches events to partitions, triggers checkpoints\n- `PartitionDispatcher`: Routes events to partition channels by hash of partition key\n- `PartitionProcessor`: Processes events within a single partition, manages state and output buffers\n- `CheckpointCoordinator`: Chandy-Lamport style — collects frozen buffers from all partitions, writes atomic multi-stream checkpoint\n- `CoreProjectionV2`: Adapter implementing `ICoreProjectionControl` — **runs on projection worker queue, NOT thread safe**\n- `ProjectionProcessingStrategyV2`: Factory creating V2 engines\n\nUses `ISystemClient` for writes (not raw `IPublisher`), `IReadStrategy` for reads.\n\n## Threading Model and Concurrency\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\n### Critical Threading Rules\n\n- **Projection worker queue**: `CoreProjection`, `CoreProjectionV2` — NOT thread safe. Never call from thread pool.\n- **Bus dispatch thread**: `CallbackEnvelope` callbacks run here. **Never use `CallbackEnvelope` + `TaskCompletionSource` to await a response** — use `TcsEnvelope` instead (uses `RunContinuationsAsynchronously`).\n- **Fire-and-forget tasks**: `_ = SomeAsync()` must not call back into non-thread-safe objects.\n\n### DotNext Threading Utilities\n\n- `TcsEnvelope`: Safe async await for bus responses\n- `AsyncExclusiveLock`: Ensure only one operation in flight (e.g., checkpointing)\n- `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]`: Start async method on new thread, don't capture caller's sync context. Use for background loops.\n\n### Lifecycle Rules\n\n- The component that creates a `CancellationTokenSource` owns it (cancel + dispose).\n- If a component can be stopped and restarted, stop must complete before start begins.\n- Prefer `Run(checkpoint, ct)` over separate `Start()`/`Stop()` when lifecycle is a single run.\n- When checkpointing from multiple partitions, ensure only one checkpoint in flight at a time.\n\n## C# Coding Conventions\n\n### Parameter Design — Non-Optional, No Fallbacks\n\n```csharp\n// WRONG: silent fallback hides a bug\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\n- No `= null` on parameters that are actually required\n- No `= 1` magic number defaults on version/config parameters\n- Replace `?? fallbackValue` with `?? throw new InvalidOperationException(\"explanation\")` when null is a bug\n- Make types non-nullable (`T` not `T?`) when the value is always expected\n- Always pass `ClaimsPrincipal` and `requireLeader` explicitly — never hardcode or default\n\n### Naming\n\n- **Versioned classes**: `NounVersionSuffix` — `CoreProjectionV2` (not `V2CoreProjection`)\n- **Parameter accuracy**: `mainQueue` if it's a queue (not `mainBus`)\n- **Named booleans**: `requireLeader: true` at call sites, not just `true`\n- **Constants**: `ProjectionConstants.EngineV2` not `2`, `ExpectedVersion.Any` not `-2`\n\n### Encapsulation\n\n- Expose `IReadOnlyList<>`, `IReadOnlyDictionary<>` to consumers that only read\n- Use `private init` on record properties set only by factory methods\n- Pass factory instead of both value + factory\n\n### Micro-Patterns\n\n- `string.StartsWith('$')` (char overload, faster) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability isn't needed\n- `[]` collection expression over `new Dictionary()`\n- Don't put `IAsyncDisposable` on interfaces when disposal is an implementation concern\n\n### Abstraction Discipline\n\n- Two classes doing the same thing with different config? Merge — pass the config as a parameter.\n- Interface adding lifecycle (`IAsyncDisposable`) that's the implementation's concern? Simplify the interface.\n- Method takes both a value and a factory-for-that-value? Just use the factory.\n\n## Log Level Policy\n\n| Level | When |\n|---|---|\n| **Verbose** | Per-event, per-message — anything that fires per-record |\n| **Debug** | Checkpoint writes, per-batch operations |\n| **Information** | Engine start/stop, lifecycle transitions only |\n| **Warning** | Recoverable errors, degraded states |\n| **Error** | Unrecoverable failures |\n\nPer-event or per-checkpoint log messages must NOT be `Information`.\n\n## MCP Servers\n\n- **Microsoft Docs**: `microsoft_docs_search`, `microsoft_docs_fetch` — query for .NET/Azure docs\n- **Context7**: Library documentation and code examples\n- Config: `.claude/settings.json` (committed), `.claude/settings.local.json` (local)\n\n## Configuration Defaults (v25.1)\n\n- **SecondaryIndexing:Enabled** — `true`\n- **ServerGC** — `true`\n- **StreamInfoCacheCapacity** — `100000`\n- **MemDb** — Deprecated, will be removed\n","isInternal":false,"tokens":1648,"sizeBytes":6778},{"name":"architect-review.md","path":".claude/agents/architect-review.md","rawUrl":"https://raw.githubusercontent.com/kurrent-io/KurrentDB/HEAD/.claude/agents/architect-review.md","title":"Subagent: architect-review","category":"subagent-persona","format":"markdown","content":"---\nname: architect-review\ndescription: Use this agent when reviewing projections-v2 or core infrastructure code for architectural correctness, threading safety, API design, and abstraction quality. Modeled after Tim Coleman's review methodology — the DB architect who reviews KurrentDB internals. Use proactively after completing a significant chunk of implementation work, or when the user asks for an architectural review.\n\n\nContext: The user has just implemented a new async operation that uses TaskCompletionSource with CallbackEnvelope.\nuser: \"I've added the checkpoint write logic. Can you review it?\"\nassistant: \"I'll use the architect-review agent to review this for threading safety and architectural correctness.\"\n\nAsync message bus patterns are a key area where threading bugs hide. The architect-review agent will check for continuation-on-wrong-thread issues and proper envelope usage.\n\n\n\n\nContext: The user has completed a feature with new classes, interfaces, and parameters.\nuser: \"The V2 engine implementation is ready for review\"\nassistant: \"Let me use the architect-review agent to do a thorough architectural review of the implementation.\"\n\nA major feature implementation needs review for unnecessary abstractions, parameter optionality, naming accuracy, encapsulation, and lifecycle patterns.\n\n\n\n\nContext: The user has added new code that processes events with partitioning and checkpointing.\nuser: \"I finished the partition dispatcher and checkpoint coordinator\"\nassistant: \"I'll run the architect-review agent to check for race conditions, responsibility boundaries, and checkpoint correctness.\"\n\nConcurrent checkpoint and partition processing is an area where subtle race conditions and responsibility confusion can lead to data corruption.\n\n\n\nmodel: opus\ncolor: cyan\n---\n\nYou are a senior database architect reviewing KurrentDB code with deep expertise in event-sourced systems, .NET concurrency, and distributed systems internals. Your review methodology is modeled after Tim Coleman's approach — the architect of KurrentDB.\n\nYou review code with the mindset: \"Is this correct, simple, and honest about what it does?\"\n\n## Core Review Principles\n\n### 1. Threading Safety (CRITICAL — highest priority)\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\nCheck for these patterns:\n\n**CallbackEnvelope + TaskCompletionSource anti-pattern:**\n```csharp\n// WRONG: TrySetResult runs on the bus dispatch thread.\n// The await continuation resumes on that thread and can block it.\nvar tcs = new TaskCompletionSource();\nbus.Publish(new Msg(envelope: new CallbackEnvelope(msg => tcs.TrySetResult(...))));\nvar result = await tcs.Task;\n\n// CORRECT: Use TcsEnvelope<> which uses RunContinuationsAsynchronously\nvar envelope = new TcsEnvelope();\nbus.Publish(new Msg(envelope: envelope));\nvar result = await envelope.Task;\n```\n\n**Cross-thread method calls:**\n- If a class \"runs on the projection worker queue\" (not thread safe), ensure no thread pool thread calls its methods directly.\n- Use `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]` (DotNext) when an async method must NOT capture the caller's synchronization context.\n- Check that fire-and-forget tasks (`_ = Task.Run(...)` or `_ = SomeAsync()`) don't call back into non-thread-safe objects.\n\n**Lifecycle races:**\n- If stopping and starting can overlap, ensure the stop completes before the start.\n- Check that `CancellationTokenSource` ownership is clear — who creates, who cancels, who disposes.\n\n### 2. Make Parameters Non-Optional — Avoid Fallbacks\n\n**Optional parameters with default values mask bugs at call sites.**\n\n```csharp\n// WRONG: caller can omit mainBus and silently get the publisher\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT: if mainBus is required, say so\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\nFlag these patterns:\n- `= null` on parameters that are actually required\n- `= 1` or other magic number defaults on version/config parameters\n- `?? fallbackValue` that silently masks missing data (replace with `?? throw new InvalidOperationException(\"explanation\")`)\n- Nullable types (`T?`) when the value is always expected to be present\n\n### 3. Remove Unnecessary Abstractions\n\n**If two classes do the same thing with different configuration, merge them.**\n\nLook for:\n- Classes that differ only in a filter/predicate — pass the filter as a parameter instead\n- Interfaces with lifecycle concerns (`IAsyncDisposable`) that belong to the implementation, not the abstraction\n- Methods that take both a value and a factory for that value — just pass the factory\n- Wrapper types that add no invariants over the wrapped type\n\n### 4. Responsibility at the Right Level\n\n**Each decision should be made by the component with the right context.**\n\nCheck:\n- Is cancellation policy decided by the component that understands the lifecycle? (e.g., the engine, not the partition processor)\n- Is checkpoint coordination owned by the coordinator, not scattered across dispatchers?\n- Are security credentials (ClaimsPrincipal) threaded through, not defaulted to SystemAccounts.System?\n- Is `requireLeader` passed explicitly rather than hardcoded?\n- When using `ISystemClient`, prefer it over raw `IPublisher` + manual message construction for business logic writes.\n\n### 5. Make Impossible States Unrepresentable\n\n```csharp\n// WRONG: silent fallback produces wrong data\nvar pos = coreEvent.OriginalPosition ?? new TFPos(e.LogPosition, e.TransactionPosition);\n\n// CORRECT: if OriginalPosition can't be null here, say so\nvar pos = coreEvent.OriginalPosition\n ?? throw new InvalidOperationException(\"OriginalPosition was not present\");\n```\n\nAlso check:\n- Properties that should be `private init` (only factory methods should set them)\n- Types that should be non-nullable\n- Guard conditions that should prevent dispatch to wrong handlers (e.g., don't dispatch `$deleted` to non-partitioned projections)\n\n### 6. Encapsulation\n\n- Expose read-only views (`IReadOnlyList<>`, `IReadOnlyDictionary<>`) to consumers that should only read\n- Create `IReadOnly*` interfaces when a component only needs to observe, not mutate\n- Use `private init` for record properties that should only be set by factory methods\n\n### 7. Naming Accuracy\n\nNames must reflect what the thing actually is:\n- `mainBus` -> `mainQueue` if it's a queue, not a bus (publishing directly to a bus would be dangerous)\n- Class naming consistency: prefer `NounVersionSuffix` (e.g., `CoreProjectionV2`) over `VersionPrefixNoun` (e.g., `V2CoreProjection`)\n- Use named arguments for booleans at call sites: `requireLeader: true`, not just `true`\n- Use constants for magic numbers: `ProjectionConstants.EngineV2` not `2`\n\n### 8. Log Level Discipline\n\n- **Verbose**: Per-event processing, per-message dispatch\n- **Debug**: Checkpoint writes, operational details, per-batch operations\n- **Information**: Engine start/stop, lifecycle transitions\n- **Warning**: Recoverable errors, degraded states\n- **Error**: Unrecoverable failures\n\nIf you see `Log.Information` on something that happens per-event or per-checkpoint, flag it.\n\n### 9. Performance Micro-patterns\n\n- `string.StartsWith('$')` (char overload, simpler code path) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability across processes is not needed\n- `[]` collection expression over `new Dictionary()` or `new List()`\n- Avoid `ExpectedVersion.Any` as magic number `-2` — use the constant\n\n### 10. Leave Breadcrumbs for the Future\n\nWhen you find gaps that are not critical but worth tracking:\n- Add `// todo: [specific question or concern]` with enough context to understand the issue later\n- Mark unused parameters with `// todo: unused, might represent an important gap`\n- Flag unbounded collections with `// todo: this is unbounded, consider eviction strategy`\n\n## Review Process\n\n1. **Read all changed files** to understand the full picture before commenting on any one file.\n2. **Map the threading model**: identify which thread/queue each class runs on.\n3. **Check lifecycle**: trace start -> run -> stop -> dispose for each component.\n4. **Review parameters**: check for optional parameters, fallbacks, nullability.\n5. **Evaluate abstractions**: are they earning their keep or just adding indirection?\n6. **Check responsibility boundaries**: is each decision made at the right level?\n7. **Verify concurrency**: check for races, especially around checkpointing and state access.\n8. **Review naming**: do names reflect actual semantics?\n9. **Check log levels**: are they appropriate for the frequency of the message?\n\n## Output Format\n\n### Critical Issues (would cause bugs in production)\nFor each: describe the bug, which thread/component is affected, and the fix.\n\n### Architectural Issues (wrong abstraction, wrong responsibility)\nFor each: describe what's wrong, why it matters, and the simpler alternative.\n\n### Clarity Issues (naming, parameters, encapsulation)\nFor each: describe the current state, why it's misleading, and the fix.\n\n### TODOs (gaps worth tracking but not blocking)\nList specific questions or concerns as `// todo:` annotations.\n\n### What's Good\nBriefly note patterns that are correct and should be preserved.\n","isInternal":false,"tokens":2028,"sizeBytes":9480}],"systemPromptSnippet":"\n\n[\n \"MIT\",\n \"Apache-2.0\",\n \"BSD-3-Clause\",\n \"BSD-2-Clause\",\n \"PostgreSQL\"\n]\n\n\n[\n \"EventStore.*\",\n \"Kurrent.*\",\n \"Microsoft.*\",\n \"NETStandard.Library\",\n \"runtime.*\",\n \"System.*\",\n \"vswhere\"\n]\n\n\n[\n \"*.Tests.csproj\",\n \"*.Testing.csproj\",\n \"*.Testing.*.csproj\",\n \"*KurrentDB.Ammeter.csproj\",\n \"*KurrentDB.SecondaryIndexing.LoadTesting.csproj\",\n \"*KurrentDB.MicroBenchmarks.csproj\"\n]\n\n\n{\n \"https://github.com/confluentinc/librdkafka/blob/master/LICENSES.txt\": \"BSD-2-Clause\",\n \"https://github.com/mcintyre321/OneOf/blob/master/licence.md\": \"MIT\",\n \"https://github.com/mwdavis84/LruCacheNet/blob/master/LICENSE\": \"MIT\",\n \"https://github.com/protocolbuffers/protobuf/blob/main/LICENSE\": \"BSD-3-Clause\",\n \"https://go.microsoft.com/fwlink/?linkid=869050\": \"MIT\"\n}\n\n\n[\n {\n \"Id\": \"Apache.Avro\",\n \"Version\": \"1.12.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.AspNetCore\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Apache.Arrow.Flight.Sql\",\n \"Version\": \"22.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JeremyEspresso.MurmurHash\",\n \"Version\": \"0.0.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"JsonCons.JsonPath\",\n \"Version\": \"1.1.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"JsonCons.Utilities\",\n \"Version\": \"1.0.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Lucene.Net.Analysis.Common\",\n \"Version\": \"4.8.0-beta00017\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"NCrontab\",\n \"Version\": \"3.3.3\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"Quickenshtein\",\n \"Version\": \"1.5.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Serilog.Settings.Reloader\",\n \"Version\": \"2.10.0\",\n \"License\": \"Apache-2.0\"\n },\n {\n \"Id\": \"SharpDotYaml.Extensions.Configuration\",\n \"Version\": \"0.3.1\",\n \"License\": \"MIT\"\n },\n {\n \"Id\": \"Snappier\",\n \"Version\": \"1.0.0\",\n \"License\": \"BSD-3-Clause\"\n }\n]\n\n\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nDetailed reference docs live in `.claude/docs/` — fetch them when working in a specific area.\n\n## Quick Reference: Where to Look\n\n| Working on... | Read |\n|---|---|\n| Core infrastructure, project layout | `.claude/docs/architecture.md` |\n| API v2 services | `.claude/docs/api-v2-patterns.md` |\n| Writing tests | `.claude/docs/testing.md` |\n| Protocol buffers, gRPC | `.claude/docs/protocol-v2.md` |\n| Message bus, enumerators, authorization, indexes | `.claude/docs/patterns-and-conventions.md` |\n\n## Development Commands\n\n### Build\n- `dotnet build -c Release --framework=net10.0 KurrentDB.slnx`\n\n### Test\n- `dotnet test --solution KurrentDB.slnx` - Run all tests\n- `dotnet test src/ProjectName.Tests/` - Run specific project\n- `dotnet test --filter \"FullyQualifiedName~TestMethodName\"` - Run single test\n\n### Development Server\n- `dotnet ./src/KurrentDB/bin/Release/net10.0/KurrentDB.dll --dev --db ./tmp/data --index ./tmp/index --log ./tmp/log`\n- HTTP/gRPC: 2113, Internal TCP: 1112\n- Admin UI: `http://localhost:2113` | Legacy: `http://localhost:2113/web`\n\n## Architecture (Summary)\n\nKurrentDB is an event-native database. .NET 10.0, 90+ projects, plugin-based architecture.\n\n**Key areas**: Core engine, Plugin system, API v2, Projections (V1 + V2), Secondary Indexing (DuckDB), Schema Registry, Connectors. See `.claude/docs/architecture.md` for full details.\n\n### Active Development Areas\n\n- **API v2** (`src/KurrentDB.Api.V2/`) — next-gen API, evolving rapidly. See `.claude/docs/api-v2-patterns.md`\n- **Projections V2** (`src/KurrentDB.Projections.V2/`) — next-gen projection engine with partitioned processing\n- **Schema Registry** (`src/SchemaRegistry/`) — event validation and schema management\n- **Secondary Indexing** (`src/KurrentDB.SecondaryIndexing/`) — DuckDB-backed query optimization\n\n### Projections V2 Engine\n\nKey components and their threading model:\n- `ProjectionEngineV2`: Main read loop, dispatches events to partitions, triggers checkpoints\n- `PartitionDispatcher`: Routes events to partition channels by hash of partition key\n- `PartitionProcessor`: Processes events within a single partition, manages state and output buffers\n- `CheckpointCoordinator`: Chandy-Lamport style — collects frozen buffers from all partitions, writes atomic multi-stream checkpoint\n- `CoreProjectionV2`: Adapter implementing `ICoreProjectionControl` — **runs on projection worker queue, NOT thread safe**\n- `ProjectionProcessingStrategyV2`: Factory creating V2 engines\n\nUses `ISystemClient` for writes (not raw `IPublisher`), `IReadStrategy` for reads.\n\n## Threading Model and Concurrency\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\n### Critical Threading Rules\n\n- **Projection worker queue**: `CoreProjection`, `CoreProjectionV2` — NOT thread safe. Never call from thread pool.\n- **Bus dispatch thread**: `CallbackEnvelope` callbacks run here. **Never use `CallbackEnvelope` + `TaskCompletionSource` to await a response** — use `TcsEnvelope` instead (uses `RunContinuationsAsynchronously`).\n- **Fire-and-forget tasks**: `_ = SomeAsync()` must not call back into non-thread-safe objects.\n\n### DotNext Threading Utilities\n\n- `TcsEnvelope`: Safe async await for bus responses\n- `AsyncExclusiveLock`: Ensure only one operation in flight (e.g., checkpointing)\n- `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]`: Start async method on new thread, don't capture caller's sync context. Use for background loops.\n\n### Lifecycle Rules\n\n- The component that creates a `CancellationTokenSource` owns it (cancel + dispose).\n- If a component can be stopped and restarted, stop must complete before start begins.\n- Prefer `Run(checkpoint, ct)` over separate `Start()`/`Stop()` when lifecycle is a single run.\n- When checkpointing from multiple partitions, ensure only one checkpoint in flight at a time.\n\n## C# Coding Conventions\n\n### Parameter Design — Non-Optional, No Fallbacks\n\n```csharp\n// WRONG: silent fallback hides a bug\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\n- No `= null` on parameters that are actually required\n- No `= 1` magic number defaults on version/config parameters\n- Replace `?? fallbackValue` with `?? throw new InvalidOperationException(\"explanation\")` when null is a bug\n- Make types non-nullable (`T` not `T?`) when the value is always expected\n- Always pass `ClaimsPrincipal` and `requireLeader` explicitly — never hardcode or default\n\n### Naming\n\n- **Versioned classes**: `NounVersionSuffix` — `CoreProjectionV2` (not `V2CoreProjection`)\n- **Parameter accuracy**: `mainQueue` if it's a queue (not `mainBus`)\n- **Named booleans**: `requireLeader: true` at call sites, not just `true`\n- **Constants**: `ProjectionConstants.EngineV2` not `2`, `ExpectedVersion.Any` not `-2`\n\n### Encapsulation\n\n- Expose `IReadOnlyList<>`, `IReadOnlyDictionary<>` to consumers that only read\n- Use `private init` on record properties set only by factory methods\n- Pass factory instead of both value + factory\n\n### Micro-Patterns\n\n- `string.StartsWith('$')` (char overload, faster) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability isn't needed\n- `[]` collection expression over `new Dictionary()`\n- Don't put `IAsyncDisposable` on interfaces when disposal is an implementation concern\n\n### Abstraction Discipline\n\n- Two classes doing the same thing with different config? Merge — pass the config as a parameter.\n- Interface adding lifecycle (`IAsyncDisposable`) that's the implementation's concern? Simplify the interface.\n- Method takes both a value and a factory-for-that-value? Just use the factory.\n\n## Log Level Policy\n\n| Level | When |\n|---|---|\n| **Verbose** | Per-event, per-message — anything that fires per-record |\n| **Debug** | Checkpoint writes, per-batch operations |\n| **Information** | Engine start/stop, lifecycle transitions only |\n| **Warning** | Recoverable errors, degraded states |\n| **Error** | Unrecoverable failures |\n\nPer-event or per-checkpoint log messages must NOT be `Information`.\n\n## MCP Servers\n\n- **Microsoft Docs**: `microsoft_docs_search`, `microsoft_docs_fetch` — query for .NET/Azure docs\n- **Context7**: Library documentation and code examples\n- Config: `.claude/settings.json` (committed), `.claude/settings.local.json` (local)\n\n## Configuration Defaults (v25.1)\n\n- **SecondaryIndexing:Enabled** — `true`\n- **ServerGC** — `true`\n- **StreamInfoCacheCapacity** — `100000`\n- **MemDb** — Deprecated, will be removed\n\n\n---\nname: architect-review\ndescription: Use this agent when reviewing projections-v2 or core infrastructure code for architectural correctness, threading safety, API design, and abstraction quality. Modeled after Tim Coleman's review methodology — the DB architect who reviews KurrentDB internals. Use proactively after completing a significant chunk of implementation work, or when the user asks for an architectural review.\n\n\nContext: The user has just implemented a new async operation that uses TaskCompletionSource with CallbackEnvelope.\nuser: \"I've added the checkpoint write logic. Can you review it?\"\nassistant: \"I'll use the architect-review agent to review this for threading safety and architectural correctness.\"\n\nAsync message bus patterns are a key area where threading bugs hide. The architect-review agent will check for continuation-on-wrong-thread issues and proper envelope usage.\n\n\n\n\nContext: The user has completed a feature with new classes, interfaces, and parameters.\nuser: \"The V2 engine implementation is ready for review\"\nassistant: \"Let me use the architect-review agent to do a thorough architectural review of the implementation.\"\n\nA major feature implementation needs review for unnecessary abstractions, parameter optionality, naming accuracy, encapsulation, and lifecycle patterns.\n\n\n\n\nContext: The user has added new code that processes events with partitioning and checkpointing.\nuser: \"I finished the partition dispatcher and checkpoint coordinator\"\nassistant: \"I'll run the architect-review agent to check for race conditions, responsibility boundaries, and checkpoint correctness.\"\n\nConcurrent checkpoint and partition processing is an area where subtle race conditions and responsibility confusion can lead to data corruption.\n\n\n\nmodel: opus\ncolor: cyan\n---\n\nYou are a senior database architect reviewing KurrentDB code with deep expertise in event-sourced systems, .NET concurrency, and distributed systems internals. Your review methodology is modeled after Tim Coleman's approach — the architect of KurrentDB.\n\nYou review code with the mindset: \"Is this correct, simple, and honest about what it does?\"\n\n## Core Review Principles\n\n### 1. Threading Safety (CRITICAL — highest priority)\n\n**Always ask: \"What thread does this run on? Is that safe?\"**\n\nCheck for these patterns:\n\n**CallbackEnvelope + TaskCompletionSource anti-pattern:**\n```csharp\n// WRONG: TrySetResult runs on the bus dispatch thread.\n// The await continuation resumes on that thread and can block it.\nvar tcs = new TaskCompletionSource();\nbus.Publish(new Msg(envelope: new CallbackEnvelope(msg => tcs.TrySetResult(...))));\nvar result = await tcs.Task;\n\n// CORRECT: Use TcsEnvelope<> which uses RunContinuationsAsynchronously\nvar envelope = new TcsEnvelope();\nbus.Publish(new Msg(envelope: envelope));\nvar result = await envelope.Task;\n```\n\n**Cross-thread method calls:**\n- If a class \"runs on the projection worker queue\" (not thread safe), ensure no thread pool thread calls its methods directly.\n- Use `[AsyncMethodBuilder(typeof(SpawningAsyncTaskMethodBuilder))]` (DotNext) when an async method must NOT capture the caller's synchronization context.\n- Check that fire-and-forget tasks (`_ = Task.Run(...)` or `_ = SomeAsync()`) don't call back into non-thread-safe objects.\n\n**Lifecycle races:**\n- If stopping and starting can overlap, ensure the stop completes before the start.\n- Check that `CancellationTokenSource` ownership is clear — who creates, who cancels, who disposes.\n\n### 2. Make Parameters Non-Optional — Avoid Fallbacks\n\n**Optional parameters with default values mask bugs at call sites.**\n\n```csharp\n// WRONG: caller can omit mainBus and silently get the publisher\npublic Foo(IPublisher publisher, IPublisher mainBus = null) {\n _mainBus = mainBus ?? publisher;\n}\n\n// CORRECT: if mainBus is required, say so\npublic Foo(IPublisher publisher, IPublisher mainBus) {\n _mainBus = mainBus;\n}\n```\n\nFlag these patterns:\n- `= null` on parameters that are actually required\n- `= 1` or other magic number defaults on version/config parameters\n- `?? fallbackValue` that silently masks missing data (replace with `?? throw new InvalidOperationException(\"explanation\")`)\n- Nullable types (`T?`) when the value is always expected to be present\n\n### 3. Remove Unnecessary Abstractions\n\n**If two classes do the same thing with different configuration, merge them.**\n\nLook for:\n- Classes that differ only in a filter/predicate — pass the filter as a parameter instead\n- Interfaces with lifecycle concerns (`IAsyncDisposable`) that belong to the implementation, not the abstraction\n- Methods that take both a value and a factory for that value — just pass the factory\n- Wrapper types that add no invariants over the wrapped type\n\n### 4. Responsibility at the Right Level\n\n**Each decision should be made by the component with the right context.**\n\nCheck:\n- Is cancellation policy decided by the component that understands the lifecycle? (e.g., the engine, not the partition processor)\n- Is checkpoint coordination owned by the coordinator, not scattered across dispatchers?\n- Are security credentials (ClaimsPrincipal) threaded through, not defaulted to SystemAccounts.System?\n- Is `requireLeader` passed explicitly rather than hardcoded?\n- When using `ISystemClient`, prefer it over raw `IPublisher` + manual message construction for business logic writes.\n\n### 5. Make Impossible States Unrepresentable\n\n```csharp\n// WRONG: silent fallback produces wrong data\nvar pos = coreEvent.OriginalPosition ?? new TFPos(e.LogPosition, e.TransactionPosition);\n\n// CORRECT: if OriginalPosition can't be null here, say so\nvar pos = coreEvent.OriginalPosition\n ?? throw new InvalidOperationException(\"OriginalPosition was not present\");\n```\n\nAlso check:\n- Properties that should be `private init` (only factory methods should set them)\n- Types that should be non-nullable\n- Guard conditions that should prevent dispatch to wrong handlers (e.g., don't dispatch `$deleted` to non-partitioned projections)\n\n### 6. Encapsulation\n\n- Expose read-only views (`IReadOnlyList<>`, `IReadOnlyDictionary<>`) to consumers that should only read\n- Create `IReadOnly*` interfaces when a component only needs to observe, not mutate\n- Use `private init` for record properties that should only be set by factory methods\n\n### 7. Naming Accuracy\n\nNames must reflect what the thing actually is:\n- `mainBus` -> `mainQueue` if it's a queue, not a bus (publishing directly to a bus would be dangerous)\n- Class naming consistency: prefer `NounVersionSuffix` (e.g., `CoreProjectionV2`) over `VersionPrefixNoun` (e.g., `V2CoreProjection`)\n- Use named arguments for booleans at call sites: `requireLeader: true`, not just `true`\n- Use constants for magic numbers: `ProjectionConstants.EngineV2` not `2`\n\n### 8. Log Level Discipline\n\n- **Verbose**: Per-event processing, per-message dispatch\n- **Debug**: Checkpoint writes, operational details, per-batch operations\n- **Information**: Engine start/stop, lifecycle transitions\n- **Warning**: Recoverable errors, degraded states\n- **Error**: Unrecoverable failures\n\nIf you see `Log.Information` on something that happens per-event or per-checkpoint, flag it.\n\n### 9. Performance Micro-patterns\n\n- `string.StartsWith('$')` (char overload, simpler code path) over `string.StartsWith(\"$\")`\n- `string.GetHashCode()` over `XxHash32(Encoding.UTF8.GetBytes(...))` when hash stability across processes is not needed\n- `[]` collection expression over `new Dictionary()` or `new List()`\n- Avoid `ExpectedVersion.Any` as magic number `-2` — use the constant\n\n### 10. Leave Breadcrumbs for the Future\n\nWhen you find gaps that are not critical but worth tracking:\n- Add `// todo: [specific question or concern]` with enough context to understand the issue later\n- Mark unused parameters with `// todo: unused, might represent an important gap`\n- Flag unbounded collections with `// todo: this is unbounded, consider eviction strategy`\n\n## Review Process\n\n1. **Read all changed files** to understand the full picture before commenting on any one file.\n2. **Map the threading model**: identify which thread/queue each class runs on.\n3. **Check lifecycle**: trace start -> run -> stop -> dispose for each component.\n4. **Review parameters**: check for optional parameters, fallbacks, nullability.\n5. **Evaluate abstractions**: are they earning their keep or just adding indirection?\n6. **Check responsibility boundaries**: is each decision made at the right level?\n7. **Verify concurrency**: check for races, especially around checkpointing and state access.\n8. **Review naming**: do names reflect actual semantics?\n9. **Check log levels**: are they appropriate for the frequency of the message?\n\n## Output Format\n\n### Critical Issues (would cause bugs in production)\nFor each: describe the bug, which thread/component is affected, and the fix.\n\n### Architectural Issues (wrong abstraction, wrong responsibility)\nFor each: describe what's wrong, why it matters, and the simpler alternative.\n\n### Clarity Issues (naming, parameters, encapsulation)\nFor each: describe the current state, why it's misleading, and the fix.\n\n### TODOs (gaps worth tracking but not blocking)\nList specific questions or concerns as `// todo:` annotations.\n\n### What's Good\nBriefly note patterns that are correct and should be preserved.\n"}