Read the root and nearest project-local AGENTS.md before changing this solution. The product specification is product-specification.md. The documentation index lists the canonical Feature specifications; each owning Feature defines stable REQ/AC, callers, boundaries, flows, tests and a Mermaid diagram. The ADR catalog records decisions with their implementation contracts. This document is a navigation map, not a replacement specification or a readiness claim: the diagrams show ownership and contracts, not proof that every target is implemented or qualified.
KeyLoad is one database for AI agents. Documents, typed tables, graphs, blobs, queues, events, vectors/search and time series coexist in one database and reference one another through canonical identities. Logical tables, collections and queues organize that one database; they are not isolated model silos.
SQL is the familiar shared language for combining those models in one bounded request. T-SQL syntax is parsed with Microsoft ScriptDOM and lowered into closed typed operations (ADR-130); SQL, the .NET SDK and MCP all reach the same authorized bounded database operations (ADR-054, ADR-065, versioned conformance inventory). The motivating flows are queue messages -> referenced entities -> knowledge graph, and graph relationships -> queued actions, owned by DatabaseComposition and ADR-067. Typed rows reuse collection entity storage so graph and vector references keep one identity (RelationalStorage, ADR-055).
flowchart LR
Caller[Agent SQL SDK MCP] --> Connection[Orleans connection grain]
Connection --> Tx[Authorized same partition ordered ZoneTree transaction]
Tx --> Source[Ready queue links or visible graph traversal]
Source --> Refs[Canonical document and typed row references]
Refs --> Effects[Graph edges or queued actions]
Effects --> Atomic[Primitive effects outbox and stable outcome]
classDiagram
Mutation <|-- QueueToGraph
Mutation <|-- GraphToQueueMutation
QueueGraphLink --> EntityRef : canonical endpoints
CommandRequest --> Mutation : ordered source and effect stages
DatabaseEngine --> QueueGraphLink : authorized transaction expansion
DatabaseEngine --> ReadExecutionBudget : cumulative deterministic bounds
Microsoft Orleans is the cluster (ADR-136, ADR-036). Orleans does all of the clustering: membership, silo discovery, failure detection, the distributed grain directory, placement, activation migration and repartitioning, internal communication (grain calls, Grain Service calls and Orleans streams), timers, reminders, durable jobs and scaling. KeyLoad adds no clustering mechanism of its own; scaling means adding silos to the Orleans cluster.
- Connection grain. Every connected client has one Orleans grain (ADR-125, connection ownership). Each operation carries its own verified identity, fresh persisted authorization, bounded admission, cancellation and idempotent command outcome. The connection grain never caches trusted roles and never owns storage.
- Partition grains. A logical partition grain is an ordinary Orleans grain that serializes and routes the commands of one logical (atomic) partition.
- Silo-local ZoneTree owner. Each silo hosts a Grain Service; typed Orleans calls can address it on another silo. The physical owner retains ZoneTree, WAL/journals, locks and ordered apply. Local scoped services borrow that exact open session through DI. Isolated stores open during silo startup. Shared storage opens lazily for its ordinary database grain and closes after that activation's original work and borrowers join. Open handles never move with activations.
- Copies. The writer finds the target silos through Orleans
membership (
IClusterMembershipService/IManagementGrain) and sends the write through ordinary Orleans calls to the ZoneTree owner Grain Services onKeyLoad:ReplicaCountsilos. The write is acknowledged after every configured copy confirms persisted apply.ReplicaCountis positive, defaults to 1 and is not larger thanKeyLoad:SiloCount;KeyLoad:StorageModeselectsIsolatedVolumes(each silo owns its own disk, the default) orSharedVolume(one shared disk,ReplicaCount=1) (ADR-143). An unfinished original command can complete on a missing copy through a stable-ID retry; unrelated gaps require explicit recovery and general empty-copy restoration remains unqualified. - Request flow. Public API (HTTP, .NET SDK, MCP, SQL) -> connection grain -> partition grains -> ZoneTree owner on the same node or on other nodes through Orleans -> results are gathered -> returned to the caller.
- Background work. Queue deadlines, due and recurring work, remote
transfers, ANN projection and time-series chunk work never check leadership.
Orleans
[StatelessWorker]grains share a logical pool key. Orleans automatically creates and retires activations as load changes; application code does not address individual activations. Each activation accepts events, buffers them in memory and, on an Orleans timer whose interval is a typed option (for example 5 seconds), write the batch through the normal grain -> ZoneTree owner path. - Identifiers. Every grain key and every identifier for objects, counters and storage keys comes from one shared helper per identity kind. Keys are case-sensitive.
flowchart LR
Caller[HTTP SDK MCP SQL caller] --> Api[Public API and ASP.NET Core authentication]
Api --> Connection[Connection grain one per client]
Connection --> Partition[Logical partition grain]
Connection --> Gather[Gather results from several partitions]
Partition -.->|finds target silos| Membership[Orleans membership]
Partition -->|Orleans call| OwnerA[ZoneTree owner on silo A]
Partition -->|Orleans call| OwnerB[ZoneTree owner on silo B]
Partition -->|Orleans call| OwnerC[ZoneTree owner on silo C]
Gather -->|Orleans calls| OwnerA
Gather -->|Orleans calls| OwnerB
OwnerA --> FilesA[(Local ZoneTree files)]
OwnerB --> FilesB[(Local ZoneTree files)]
OwnerC --> FilesC[(Local ZoneTree files)]
Events[Background events] --> Worker[StatelessWorker grain buffer]
Worker -->|Orleans timer batch| Partition
Two storage modes are required. With a shared volume, all silos can reach the configured partition paths without copying data. One ordinary Orleans grain owns each open physical partition; the other silos call it. Orleans owns activation placement and movement. The storage owner closes its actual handles before another activation reopens that partition. ZoneTree's WAL opens with exclusive file sharing, so several live writable instances over the same files are unsupported. The actual filesystem must preserve the required locking and flush semantics.
With isolated volumes, typed Orleans calls reach the owners of the required logical partitions. The caller bounds parallel work and merges partial results. A physical replica is another copy of one partition, not another partition to count in the result. Stateless workers perform interchangeable Task-based work using Orleans-managed activation pools.
The source implements lazy shared-session acquisition and joined close, isolated
full-copy routing, and ordinary partition grains for PartitionQuery and
DistributedSearch. A request pins one actual owner per distinct logical
partition and preserves its expiry, cumulative budgets and read-cut checks across
all leaf stages. Full copies remain copies of the same database; this does not
implement a partition-to-disk sharding scheme. Both modes still require complete
runtime and exact-source Linux qualification, including the deployed shared
volume's locking and flush behavior.
Sources: Orleans stateless workers, grain directory, and the pinned ZoneTree WAL open contract.
Credentials and authorization policies are persisted in the database; callers never supply trusted roles. Standard ASP.NET Core authentication admits HTTP, SDK and MCP callers, and ManagedCode.Orleans.Identity carries the verified call-local identity between grains. OpenTelemetry logs, traces and metrics come from the Orleans, ASP.NET Core and Aspire integrations without credentials, payloads or unbounded labels. Orleans execution and scheduling choices are mapped per grain and method in ExecutionPrimitives and ADR-110; the broader Orleans capability review covers Streams, transactions, durable jobs and per-silo services. Orleans transactional grain state does not by itself make ZoneTree writes atomic; it needs a provider that participates in the canonical ZoneTree commit.
Runtime projects under src/ have distinct consumers and responsibilities:
Abstractions (shared contracts), Client (external SDK), Cli (operator
executable), Core (database semantics and authorization evaluation), Query (SQL
compilation, search and change feeds), Clustering (Orleans grains, routing and
copies through calls to ReplicaCount silo-local ZoneTree owners),
Storage.ZoneTree (physical storage, local archive transfer and file IO),
Server (host composition, public API, health, service discovery, resilience and
OpenTelemetry) and Diagnostics (BCL-only bounded phase telemetry shared by
storage and replication). Diagnostics stays independent so low-level storage
does not depend on domain execution or the server host.
src/ contains runtime product code only. Compiler rules live in analyzers/;
the Aspire AppHost and shared build targets live in build/; tests and
benchmarks keep their own roots. Recovery tests own their child-process
scenarios in the same test assembly. Compiler analyzers, the AppHost, benchmark
entry, generated-consumer fixtures, the execution
comparison library and the TUnit comparison host keep their distinct execution
boundaries.
Each Program.cs shows initialization, mode selection, host composition, run and
joined shutdown; compiler rule KLD0020 rejects forwarding-only entry wrappers.
Runtime code reads time through an owned TimeProvider
(TimeProvider,
ADR-115), operational policy through validated
typed options (ADR-113), runtime
identities through named constants (ADR-111)
and synchronization through Orleans turns, System.Threading.Lock or
SemaphoreSlim.WaitAsync (ADR-108).
All KeyLoad-owned backend, clients, contracts, frontend, tests, infrastructure and docs live here and are versioned together. Independently owned ManagedCode dependencies remain in their owning repositories; repair, release and verified NuGet publication follow root policy.
| Project/module | Purpose and entry points | Canonical slices / protected boundary |
|---|---|---|
| src/KeyLoad.Abstractions | CommandRequest.cs, PartitionRef.cs, Mutation.cs and <SliceName>/ contract folders |
Shared public and storage contracts for every canonical slice. |
| src/KeyLoad.Core | DatabaseEngine.cs, AtomicCommandCommit.cs, CommandOutcomeApplication.cs, DocumentStorage/Execution/DocumentStorageExecutionDocuments.cs, Messaging/Execution/MessagingExecutionMessaging.cs, GraphTraversal/, TimeSeries/, Search/ | Shared node-local execution context and feature-owned operation components; authorization and model effects share the ordered atomic commit. |
| src/KeyLoad.Diagnostics | Models/DatabasePhaseKind.cs, Models/DatabasePhaseSnapshot.cs | BCL-only scalar phase observations, with no database state, public control endpoint or framework dependency. |
| src/KeyLoad.Storage.ZoneTree | ZoneTreeStore.cs, StorageEngine/Execution/ZoneTreeStoreRuntime.cs, StorageEngine/Recovery/ZoneTreeCheckpointManager.cs | StorageEngine, PointCache and Restore; files, WAL, checkpoints and local archives stay with the silo-local ZoneTree owner. |
| src/KeyLoad.Query | QueryExecution/Queries/QueryEngine.cs, QueryExecution/Execution/SqlParser.cs, Search/Queries/QueryExecution/SearchEngine.cs, ChangeFeeds/Queries/LiveQueryExecutor.cs | QueryExecution, Search, ChangeFeeds; one authorized typed AST and bounded read cut. |
| src/KeyLoad.Clustering | RequestExecution/Grains/ConnectionGrain.cs, RequestExecution/Grains/CommandPartitionGrain.cs, RequestExecution/Queries/Connections/ConnectionReadExecution.cs, <SliceName>/GrainServices/ |
OrleansExecution; connection and partition grains route through Orleans to the silo-local ZoneTree owners. |
| src/KeyLoad | Program.cs, NodeOptions.cs, ClientApi/, OrleansHosting/Hosting/OrleansNode.Composition.cs | Composition root, Orleans host and public API; caller identity never supplies trusted roles. |
| src/KeyLoad.Client | ClientApi/Transport/KeyLoadClient.cs, QueryExecution/Queries/KeyLoadQuery.cs | ClientApi transport; business operations mirror the same canonical slices as core, contracts, API and tests. |
| src/KeyLoad.Cli | Program.cs, ClientApi/Transport/CliClientApi.cs, Restore/Commands/CliBackupRestore.cs | Administrative entry point with typed ClientApi and backup/restore owners. |
| build/KeyLoad.AppHost | Program.cs, Hosting/, OrleansHosting/Resources/ClusterTelemetryResources.cs, TestInfrastructure/ | Aspire owns cluster resources, readiness, test dependencies, scoped process faults and joined shutdown. |
| tests/KeyLoad.UnitTests | TestDatabase.cs and <SliceName>/ folders |
Matching product slices; contract and engine regressions. |
| tests/KeyLoad.RecoveryTests | Program.cs, StorageRecovery/Cases/, feature-owned Processes/ and Execution/ | TUnit recovery tests and their real child-process scenarios in the same test assembly. |
| tests/KeyLoad.IntegrationTests | ClusterFixture.cs, StorageReplication/Cases/Cluster/ClusterTests.cs, ResourceExecution/Cases/AdmissionClusterTests.cs | Aspire-owned cluster fixtures; business cases mirror their owning slices through the real .NET SDK and official MCP client. |
| benchmarks/KeyLoad.ComparisonHost | Session/, Orchestration/ | Selected live benchmark topology, measured workloads and original result artifacts. |
| benchmarks/KeyLoad.Benchmarks | Program.cs | BenchmarkComparisons; embedded microbenchmark development, no public claim without CI evidence. |
| benchmarks/KeyLoad.BenchmarkScenarios | Benchmarks/EmbeddedBenchmarks.cs | BenchmarkComparisons; ADR-047 public fixture library for the external generated consumer. |
| benchmarks/KeyLoad.Comparisons | Session/, Targets/ | BenchmarkComparisons; public library with shared workload/oracle and official engine clients. |
| benchmarks/KeyLoad.ComparisonHost | Session/ | BenchmarkComparisons; TUnit C# client workload container under ADR-117. |
| site | Features/BenchmarkComparisons/index.html, bootstrap.mjs; scripts/build.mjs | BenchmarkComparisons; product introduction and public views of qualified GitHub JSON. |
| tests/KeyLoad.SiteTests | KeyLoad.SiteTests.csproj, Cases/, Fixtures/ | BenchmarkComparisons; TUnit suite over the actual Node modules and authentic GitHub report files. |
| .github/workflows | build-and-tests.yml, benchmarks.yml, website.yml, release.yml | RepositoryGovernance, BenchmarkComparisons, ReleaseDelivery; separate build/test, benchmark, website and release workflows. |
| scripts | Features/RepositoryGovernance/verify.mjs, Features/BenchmarkComparisons/session-plan.mjs | RepositoryGovernance and BenchmarkComparisons; static repository verification and benchmark session tooling with Node built-ins. |
| analyzers/KeyLoad.Analyzers | KeyLoad.Analyzers.csproj, Analyzers/, Analysis/ | CodeQuality; source-owned Roslyn diagnostics attached to compilation, never runtime storage or routing. |
| tests/KeyLoad.Analyzers.Tests | KeyLoad.Analyzers.Tests.csproj, Cases/, Fixtures/ | CodeQuality; real Roslyn/Orleans metadata checks. |
| docs | design/, Features/, ADR/, implementation/ | Product specification and canonical slice/decision records. |
flowchart TB
SDK[Public .NET SDK and CLI] --> Server[Server gateway and identity]
MCP[Official MCP SDK surface] --> Server
Server --> Orleans[Connection and partition grains]
Orleans --> Owners[Silo-local ZoneTree owner on every silo]
Owners --> Core[Atomic engine and ordered apply]
Core --> Storage[ZoneTree journals and files]
Core --> Models[Documents events queues graph search series blobs]
Aspire[Aspire Docker lifecycle] --> Owners
CI[GitHub Actions qualification] --> Aspire
CI --> JSON[Raw comparison JSON with source SHA]
JSON --> Site[README charts and Pages site]
Every C# project under src/, tests/ and benchmarks/ places named slices
directly under its project directory as <project>/<SliceName>/<Role>/. Each
slice groups actual responsibilities in populated role folders such as
Grains/, Commands/, Queries/, Models/, Contracts/, Streaming/,
Identity/, Serialization/ and Topology/; a slice is an ownership boundary,
not a flat file collection. Test support uses explicit Scenarios/, Fixtures/,
Assertions/, Contracts/, Lifecycle/, Observations/ and Serialization/
roles, with related subjects grouped beneath the role (for example
Search/Scenarios/FullText/); thematic folders stay inside Cases/. Scripts,
site and documentation keep their module paths. Namespaces, Orleans aliases and
field IDs stay stable across structural moves. The owner contract and checks are
in RepositoryGovernance and
ADR-032.
Canonical slice names use PascalCase consistently: RepositoryGovernance,
BenchmarkComparisons, DatabaseComposition, DocumentStorage, RelationalStorage,
EventStreams, Messaging, GraphTraversal, TimeSeries, Search, QueryExecution,
Authorization, ChangeFeeds, StorageRecovery, StorageReplication, OrleansExecution,
ClientApi, BackupRestore (project folder Restore/), BlobStorage,
ResourceExecution, InternalSerialization, AdminDashboard, AnalyticsStore,
CodeQuality, ReleaseDelivery and TestInfrastructure. Their owning contracts and
navigation are in the Feature index. Shared entry points,
composition roots, truly shared contracts and global infrastructure may remain
outside slice folders. A non-applicable surface is recorded as N/A with its
reason in the feature spec. Shared atomic commit and outcome dispatch stay
outside slice folders because they join multiple mutation families
(ADR-042).
sequenceDiagram
participant Caller as SDK or MCP caller
participant API as Public API
participant Conn as Connection grain
participant Part as Partition grain
participant Owners as ZoneTree owners on ReplicaCount silos
Caller->>API: Typed operation and credentials
API->>Conn: Verified subject and bounded request
Conn->>Conn: Fresh persisted authorization
Conn->>Part: Ordered command for one logical partition
Part->>Owners: Orleans calls with the command
Owners-->>Part: Durable local apply confirmations
Part-->>Conn: Outcome after every configured copy confirms
Conn-->>API: Public result
API-->>Caller: Contract result
classDiagram
class KeyLoadClient
class CommandRequest
class PartitionRef
class ConnectionGrain
class CommandPartitionGrain
class DatabaseEngine
class IKeyValueView
class IAtomicTransaction
KeyLoadClient --> CommandRequest
CommandRequest --> PartitionRef
ConnectionGrain --> CommandPartitionGrain : one logical partition
CommandPartitionGrain --> DatabaseEngine : Orleans calls to silo-local owners
DatabaseEngine --> IKeyValueView
DatabaseEngine --> IAtomicTransaction
Official MCP and simple agent adapters belong to ClientApi
and ADR-039; business operations keep
their own Feature owners. The MCP host exposes bounded search/route/invoke tools
through ManagedCode.MCPGateway and ManagedCode.MarkdownLd.Kb tool-metadata graphs
(ToolDiscovery,
ADR-104); the graph holds public
operation documentation only. Streamed results and long operations use
ManagedCode.Communication CQRS IAsyncEnumerable contracts through Orleans
(RuntimeCqrs,
ADR-082). enumeration does not move
node-owned storage or replace persisted authority.
ADR-132 defines the bounded CREATE TABLE operation with a caller-stable SQL command identity on the connection-owned execution path. Canonical typed resources stay in ZoneTree behind the ordered apply gate. The PostgreSQL wire/Npgsql session is a separately qualified transport, not a PostgreSQL grammar or SQL Server TDS promise.
classDiagram
ScriptDomSyntax --> TSqlParser : bounded grammar
SqlOperationCompiler --> ScriptDomSyntax : selected syntax
SqlOperationCompiler --> SqlOriginalMutationIdentity : original command identity
SqlOperationCompiler --> McpDecodedOperation : canonical typed plan
ScriptDomCreateTableOperation --> ScriptDomCreateTableSyntax : closed schema
CanonicalConnectionDispatch --> McpDecodedOperation : authorized execution
flowchart LR
Agent[AI agent SQL SDK MCP] --> Server[One server API]
Server --> SQL[Versioned TSQL SELECT and EXEC compiler]
SQL --> Gateway[Connection grain]
Gateway --> Owners[Partition grains and silo-local ZoneTree owners]
Owners --> Entity[Canonical documents and typed rows]
Owners --> Models[Graph search events queues series blobs]
Entity --> Models
classDiagram
ResourceDefinition --> RelationalSchema
RelationalSchema --> RelationalColumn
SqlOperationRequest --> SqlOperationCompiler
SqlOperationCompiler --> McpOperationDescriptor : canonical typed decoder
McpOperationDescriptor --> CanonicalOperationGateway
RelationalRowValidation --> DocumentRecord : validates final row image
ResourcePolicyUpdates and ADR-093 define policy-only CAS through the replicated ConfigureResource path; advancing a resource version invalidates existing cursors and index fences, and physical schema changes stay separate.
File API contracts and server transfers use ManagedCode.Storage. ZoneTree stores file metadata, access policy, publication state and physical-storage references; provider-owned physical files contain the payload bytes. Database command and replica journals carry metadata, never file content. See ADR-038 and BlobStorage for the publication boundary and open physical-provider qualification gates.
ZoneTree is the canonical storage for every KeyLoad-owned model and ZoneTree.FullTextSearch is the selected derived text index (ADR-071, FullTextProjection). The silo-local ZoneTree owner keeps WAL, ordered apply and file ownership on its node. Current storage accepts only the formats in CurrentFormat and rejects unsupported or corrupt versions before effects (ADR-011, ADR-116). Process-kill recovery tests do not prove power-loss durability.
Document CRUD handlers and transaction-scoped image carriers belong to
Core/DocumentStorage/; admission and inbox ownership belong to
Core/ResourceExecution/. DatabaseEngine holds the shared storage context,
validated policy snapshots and node-local admission state. Feature-owned static
operation components contain the command, query and validation implementations;
extension methods pass that same context explicitly. They preserve the existing
atomic transaction and persisted authorization boundary. Local numeric checks
and complete runtime qualification are separate gates
(ADR-041).
classDiagram
class DatabaseEngine
class DocumentMutationContext
class DocumentMutationResult
class DocumentRecord
class MutationReceipt
class IAtomicTransaction
DatabaseEngine --> IAtomicTransaction : atomic command gate
DatabaseEngine --> DocumentMutationContext : one prior lookup
DocumentMutationContext --> DocumentRecord : Before
DatabaseEngine --> DocumentMutationResult : CRUD return
DocumentMutationResult --> DocumentRecord : staged After
DocumentMutationResult --> MutationReceipt : exact receipt
classDiagram
ZoneTreeTransaction --> ZoneTreeJournalCodec : prepares binary payload
ZoneTreeJournalPublication --> ZoneTreeJournalCodec : validated payload
ZoneTreeJournalRecovery --> ZoneTreeJournalCodec : complete checked decode
ZoneTreeJournalCodec --> ZoneTreeJournalMutation : stable generated fields
ZoneTreeStoreInitializer --> ZoneTreeIdentityFile : current format writer fence
RuntimeReadCuts under ADR-097 supplies provider-owned snapshot lifetimes for bounded reads. A real-process inspector checks an original store without the normal runtime, then releases it for a normal reopen:
classDiagram
class ExistingStoreInspectorProcess
class ExistingStoreInspector
class ExistingStoreInspectorProtocol
class ZoneTreeExistingStore
ExistingStoreInspectorProcess --> ExistingStoreInspectorProtocol : bounded stdin
ExistingStoreInspector --> ExistingStoreInspectorProtocol : safe receipt
ExistingStoreInspector --> ZoneTreeExistingStore : owns guarded runtime
ExistingStoreInspectorProcess --> ExistingStoreInspector : original child lifetime
Public chunked blobs and partial reads belong to BlobStorage and ADR-038; backup archive pieces are a separate storage protocol.
ADR-060 and InternalSerialization require execution generated Orleans payloads with stable aliases and field IDs across owned persistence, grain requests/replies, copies sent to ZoneTree owners and signed claims. Public HTTP/MCP JSON, exact user content, frozen canonical fingerprint identities, sortable keys, raw ZoneTree values, fixed checksum framing and blob bytes keep their concrete protocols. generated bytes are not canonical hashes for unordered values. Readers reject unsupported formats before effects.
flowchart LR
Public[Public JSON protocol] --> Typed[Attributed owned DTOs]
Typed --> Execution[Cached Orleans codecs and pooled sessions]
Execution --> Records[Typed records and versioned metadata]
Execution --> Calls[Grain call payloads and copies]
Execution --> Claims[Signed claims]
Records --> Files[Node local ZoneTree and atomic WAL]
Typed --> Identity[Frozen canonical fingerprint material]
classDiagram
OrleansSerialization --> RuntimePayload : versioned generated root
OrleansSerialization --> OrleansSerializer : official generated codecs
OrleansSerializer --> OfficialJsonCodec : JsonElement only
ZoneTreeIdentityFile --> ZoneTreeMetadataBinary : explicit format fence
GrainRequestEnvelope --> GrainValue : attributed boundary
ResourceExecution and ADR-035 own common budgets in shared node-local building blocks; operation behavior stays in its canonical slice. ClientApi owns HTTP response streaming. Scoped document and vector visitors feed QueryExecution and Search without raw pages; GraphTraversal keeps cut-scoped visibility decisions. The shared canonical JSON writer streams fingerprints to a hash and preserves exact signatures.
classDiagram
class KeyLoadClient
class QueryEngine
class LiveQueryExecutor
class DatabaseEngine
class ReadExecutionBudget
class VisibleDocumentReads
class VisibleVectorReads
class GraphTraversalReader
class JsonData
class CanonicalJsonWriter
class CanonicalHashStream
class IKeyValueView
class ZoneTreeStore
class ZoneTreeStoreRuntime
class ZoneTreeTransaction
class ZoneTreeCheckpointManager
class ZoneTreeCheckpointReader
class ZoneTreeBackupRestore
KeyLoadClient --> QueryEngine : public HTTP operation
QueryEngine --> ReadExecutionBudget : scoped budget
QueryEngine --> LiveQueryExecutor : live public facade
LiveQueryExecutor --> DatabaseEngine : same authorized read cut
LiveQueryExecutor --> QueryEngine : borrowed execution and projection
QueryEngine --> VisibleDocumentReads : visible candidates
VisibleDocumentReads --> ReadExecutionBudget : borrowed scan
VisibleVectorReads --> ReadExecutionBudget : vector and document work
GraphTraversalReader --> ReadExecutionBudget : visibility and output
JsonData --> CanonicalJsonWriter : exact canonical bytes
CanonicalJsonWriter --> CanonicalHashStream : incremental fingerprint
ReadExecutionBudget --> IKeyValueView : bounded work
ZoneTreeStore ..|> IKeyValueView : gate scoped implementation
ZoneTreeStore --> ZoneTreeStoreRuntime : sole node local owner
ZoneTreeStoreRuntime --> ZoneTreeTransaction : staged atomic work
ZoneTreeStoreRuntime --> ZoneTreeCheckpointManager : generation replacement
ZoneTreeCheckpointManager --> ZoneTreeCheckpointReader : strict format
ZoneTreeStoreRuntime --> ZoneTreeBackupRestore : verified local backup
search scheduling follows ADR-081: one analytical reservation spans the complete awaited read and settlement while the connection grain yields. Index generations have bounded leases and retirement (OnlineGenerationLifetime); global retrieval merges bounded per-modality windows before RRF (GlobalBranchWindows). SIMD execution uses execution .NET vector intrinsics with scalar code only for bounded tails and independent correctness oracles (Search); acceleration claims need comparable GitHub measurements.
ADR-019, ManagedAnn and ManagedAnnSeed define the managed ANN candidate: a private builder copies bounded canonical vector input captured in one node-local read cut into owned packed arrays, and each search uses its own admitted scratch with the exact metric implementation. ANN projection updates are background work under the StatelessWorker pattern above.
classDiagram
AnnSeedCollector --> ReadExecutionBudget : one charged canonical cut
AnnSeedCollector --> AnnSeed : owned snapshot input
AnnSeed --> PackedAnnBuilder : later explicit integration
AnnWorkBudget --> ReadExecutionBudget : work and elapsed checks
PackedAnnBuilder --> PackedAnnGraph : actual level offsets
PackedAnnBuilder --> PackedAnnVectors : owned bounded blocks
PackedAnnBuilder --> PackedAnnIndex : complete immutable state
PackedAnnIndex --> AnnWorkBudget : per call admission
PackedAnnIndex --> PreparedSimilarity : unchanged scores
PackedAnnIndex --> AnnSearchResult : candidates mode and counters
ADR-052 defines the TimeSeries latest/aggregate/window slice. Typed Abstractions DTOs mirror Client, Server and Core owners. Core uses the published ManagedCode.TimeSeries library inside one budgeted storage cut, and shared StorageRecovery reverse visitors support bounded latest reads. Chunk work runs under the StatelessWorker background pattern.
classDiagram
class TimeSeriesReadOperations
class SampleLatestReader
class SampleAggregateReader
class SampleAggregateWindowReader
class SampleAggregateAccumulator
class BudgetedReadView
class ZoneTreeRangeReader
TimeSeriesReadOperations --> BudgetedReadView : one gated operation budget
TimeSeriesReadOperations --> SampleLatestReader
TimeSeriesReadOperations --> SampleAggregateReader
TimeSeriesReadOperations --> SampleAggregateWindowReader
SampleLatestReader --> ZoneTreeRangeReader : descending first live key
SampleAggregateReader --> SampleAggregateAccumulator : published sums
SampleAggregateWindowReader --> SampleAggregateAccumulator : bounded windows
ADR-058 keeps RAM acceleration under the ResourceExecution slice. The common retained pool and the embedded positive point-value cache are disposable node-local state over committed ZoneTree data. Cached state never replaces persisted authorization, committed ZoneTree state or the acknowledgement from every configured copy of copies, and it never moves files or handles.
classDiagram
class ICacheMemoryBudget {
TryReserve(bytes, entries)
GetSnapshot()
}
class ICacheMemoryReservation {
Bytes
Entries
Dispose()
}
class CacheMemoryBudget
class CacheMemoryLimits
CacheMemoryBudget ..|> ICacheMemoryBudget
ICacheMemoryBudget --> ICacheMemoryReservation
CacheMemoryBudget --> CacheMemoryLimits
class ICacheReadPermit {
IsCurrentAcceptance(receipt)
}
ZoneTreeStore --> ZoneTreeStoreRuntime
ZoneTreeStoreRuntime --> ZoneTreePointCacheLifecycle
ZoneTreePointCacheLifecycle --> ZoneTreePointCacheControl
ZoneTreePointCacheControl --> ZoneTreePointCacheControlState
ZoneTreePointCacheControlState --> ICacheReadPermit
ZoneTreePointCacheControlState --> ZoneTreePointCacheBinding
ZoneTreePointCacheBinding --> ZoneTreePointCache
ZoneTreePointCache --> ICacheMemoryBudget
ADR-063 defines the optional bounded database phase bank. Process mode is disabled by default; private capture runs outside database gates.
classDiagram
class DatabasePhaseKind
class DatabasePhaseOutcome
class DatabasePhaseBank
class DatabasePhaseSnapshot
DatabasePhaseKind --> DatabasePhaseBank : fixed source boundary
DatabasePhaseOutcome --> DatabasePhaseBank : actual owned result
DatabasePhaseBank --> DatabasePhaseSnapshot : detached cumulative capture
The AdminDashboard slice under
ADR-051 hosts the read-only console in
src/KeyLoad/AdminDashboard/Assets/, with shared Abstractions DTOs, Core
catalog/queue readers and a matching Client SDK. It uses the connection grain
with call-local authorized reads; physical observations are reported per node.
The public site/ is its own surface. Both share one visual identity under
ADR-053: the console owns the canonical
brand.css/logo.svg and the site keeps byte-identical mirrors.
SiteMetadata adds mirrored
PNG/ICO exports, static landing SEO/OG/JSON-LD and a share card.
flowchart LR
Admin[Same origin admin console] --> API[AdminDashboard API and MCP]
API --> Request[Connection grain]
Request --> Read[Call-local authorized read execution]
Read --> Core[Bounded catalog and queue readers]
Read --> Node[Node local file and process observer]
CodeQuality is a compile-time slice defined by ADR-033. Central SDK/style analysis and source-owned Roslyn rules produce compiler/IDE findings and per-project SARIF reports; builds always run with warnings as errors. This build infrastructure has no database runtime or persistence surface.
flowchart LR
Rules[CodeQuality rule sources] --> Analyzer[KeyLoad.Analyzers]
Analyzer --> Compiler[SDK Roslyn compiler and IDE]
Policy[EditorConfig and central MSBuild] --> Compiler
Projects[Solution projects] --> Compiler
Compiler --> SARIF[Compiler diagnostic reports]
Tests[Real compilation TUnit regressions] --> Analyzer
classDiagram
class DiagnosticAnalyzer
class LiteralMachineKeyAnalyzer
class OrleansGenerateSerializerAnalyzer
class CSharpCompilation
class Diagnostic
DiagnosticAnalyzer <|-- LiteralMachineKeyAnalyzer
DiagnosticAnalyzer <|-- OrleansGenerateSerializerAnalyzer
CSharpCompilation --> DiagnosticAnalyzer
DiagnosticAnalyzer --> Diagnostic
Shared benchmark sessions under ADR-142 run exactly two measurement jobs per database: one node and three nodes. Each job owns one live Aspire topology and runs separate real TUnit cases against it, starting with a measured million-record load. Original per-case outcomes, TRX, runtime/image identities and resource observations feed one authenticated complete-cohort aggregation; failed or incomplete cohorts cannot refresh published metrics. Scales are exactly 100,000 and 1,000,000 records (ScaledWorkloads, ADR-069). The owning feature holds the criteria.
flowchart LR
Plan[Canonical session inventory] --> Prepare[Common compiled runner and images]
Prepare --> Worker[One database and node count per job]
Worker --> Aspire[One owned live Aspire topology]
Aspire --> Tests[Separate TUnit workload cases]
Tests --> Originals[Original reports, TRX and runtime evidence]
Originals --> Aggregate[Complete authenticated cohort]
Aggregate --> Site[Qualified website metrics]
ADR-043 keeps the comparison library separate from the sole workload host; ADR-044 and ADR-045 own immutable harness contracts and transient PostgreSQL schemas. ADR-049 keeps genuine Neo4j protocol and acknowledgement checks inside the Aspire lifecycle, and ADR-050 compares KeyLoad time series with TimescaleDB and ManagedCode.TimeSeries, reporting each arm's storage and acknowledgement guarantees separately.
flowchart LR
ComparisonHost[Separate benchmark session owner] --> AppHost[Selected Aspire database infrastructure]
ComparisonHost --> ComparisonLibrary[Public workload and target library]
classDiagram
class ComparisonHost
class BenchmarkSession
class Neo4jTarget
class Neo4jQueryResponse
ComparisonHost --> BenchmarkSession : measured workload against actual endpoint
BenchmarkSession --> Neo4jTarget : target contract
Neo4jTarget --> Neo4jQueryResponse : parsed acknowledgement
flowchart LR
Corpus[Deterministic UTC samples] --> KeyLoad[KeyLoad cluster via SDK]
Corpus --> Timescale[TimescaleDB via Npgsql]
Corpus --> MCTS[ManagedCode.TimeSeries memory aggregation]
KeyLoad --> Oracle[Separate result and guarantees]
Timescale --> Oracle
MCTS --> Oracle
Embedded ZoneTree microbenchmarks (ADR-047) use the actual generated consumer for local development and never qualify the required scales.
classDiagram
class BenchmarkProgram
class EmbeddedBenchmarks
class GeneratedBenchmarkRunner
class ZoneTreeStore
BenchmarkProgram --> EmbeddedBenchmarks : BenchmarkSwitcher selects assembly
GeneratedBenchmarkRunner --|> EmbeddedBenchmarks : upstream generated inheritance
EmbeddedBenchmarks --> ZoneTreeStore : owns actual embedded fixture storage
ADR-080 keeps the full planned-cell inventory while terminal workload failures coexist with successful measurements: a failed job stays failed, has a null report and shows no numeric result.
flowchart LR
Job[Independent Aspire cell] --> Result[Measured or failed null report]
GitHub[Actual job steps and immutable artifact] --> Proof[Same source run attempt validation]
Result --> Proof
Proof --> Aggregate[Complete planned-cell aggregate]
Aggregate --> Qualification[Site tests browser coverage freshness]
Qualification --> Site[Values or no data and original job links]
ADR-064 and
ADR-062 define exactly four workflows.
build-and-tests.yml (Build and Tests) owns PR/main/manual build, format,
rules, analyzers, unit, process recovery and Docker/Aspire cluster SDK/MCP tests;
benchmark contracts run only in Benchmarks
(ADR-117). benchmarks.yml
(Benchmarks) owns the isolated Linux database groups and authenticated
aggregation and ends with a bounded dispatch of website.yml (Website).
Website publishes independently on trusted main changes or manual dispatch and
uses the newest ready authenticated benchmark aggregate when one exists
(ADR-112). release.yml
(Release) stays manual (ReleaseDelivery): an
immutable UTC version vM.m.yyMMdd.N, packages, self-contained server/CLI
distribution and versioned images built by the .NET SDK PublishContainer
target. Packaging does not establish runtime or endurance qualification.
flowchart LR
Source[PR or main source] --> CI[Build and Tests]
Main[Main source] --> Benchmarks[All isolated benchmarks]
Benchmarks --> Aggregate[Complete authenticated JSON]
Aggregate --> Dispatch[Settled final Website dispatch]
Dispatch --> Site[Website gates and Pages publication]
Main --> Site
Manual[Manual main release] --> Reserve[UTC date and daily number]
Reserve --> Build[Packages database distribution images]
CI --> Gate[Successful exact source proof]
Build --> Publish[Immutable tag GHCR and GitHub Release]
Gate --> Publish
flowchart LR
Source[Website source] --> Website[Separate Website qualification]
Producer[Ready Benchmarks JSON] --> Website
Website --> Content[Product site without metrics]
Website --> Measured[Product site with authenticated metrics]
Content --> Fresh[Recheck source and available data]
Measured --> Fresh
Fresh --> Pages[Pages]
Delivered-source qualification comes only from exact-source Linux GitHub runs with their original artifacts; local runs are development evidence.