Clarify connection and request grain lifetimes

Author: KSemenenko

AGENTS.md

@@ -589,3 +589,8 @@ A bounded website qualification candidate contains the20-project historical runt
 - Ingestion load qualification MUST include a one-client baseline and concurrent-client cases at 10 and 500 clients. Each case adds exactly 1,000,000 total distinct records across its clients, verifies acknowledged writes and the final stored records through real clients, and records actual client concurrency separately from native TUnit test concurrency. Bound client admission, cancellation and cleanup; retain the existing 100,000/1,000,000 dataset inventory and matched comparison contracts.
 - Owner direction2026-10-09 requires a primary-source-backed benchmark methodology and its actual implemented tests: one canonical comparable scenario set covers isolated individual operations and deterministic mixed operations at native1/3 nodes, with explicit setup/warmup/measurement/validation phases, repetitions, latency distributions, offered/completed load, errors, resource use, acknowledgement/durability and complete stored-result verification. Preserve serial measurement per job and genuine native clients/topologies; a methodology document alone does not finish the benchmark work.
 - Owner correction2026-10-09 requires all benchmark-stage builds, checks, tests and workload execution in GitHub Actions. Do not run benchmark development verification locally on the owner's computer. This scope-specific correction supersedes earlier local-development permission; retain original local failures as history and qualify the delivered source only from original Linux GitHub results.
+
+## Connection and request grain lifetimes, owner clarification 2026-10-09
+
+- Persistent client connections MUST have a distinct Orleans connection/session grain with bounded disposable session state and explicit disconnect/idle-expiry cancellation, joined cleanup and deactivation. Freeze the actual logical connection identity, transport ownership, limits and scheduling in ClientApi/QueryExecution requirements and the native-client ADR before implementation; a connection grain MUST NOT cache trusted roles or replace fresh persisted authorization for each operation. This is a required product target, not a claim that the native connection protocol is delivered.
+- Request and independently keyed read grains MUST retain no persistent operation state or completed request history. Keep request data call-scoped and bounded; after success, failure, cancellation, deadline or early stream disposal, join the original producer/capability cleanup and request native DeactivateOnIdle as part of settlement, without waiting for ordinary idle collection. Bound active work and admission/cleanup backlogs; total historical request count MUST NOT determine retained activation count. Native deactivation and CLR memory reclamation are asynchronous, so requesting deactivation alone MUST NOT be reported as measured activation or RAM recovery.

README.md

@@ -157,14 +157,16 @@ Details: [composition guide](docs/Features/DatabaseComposition.md) · [transacti
 
 ```mermaid
 flowchart LR
-    Callers["SDK · MCP · SQL · HTTP"] --> Request["One Orleans grain<br/>per request"]
+    Callers["SDK · MCP · SQL · HTTP"] --> Request["Short-lived Orleans<br/>request grain"]
     Request --> Partition["Partition grains"]
     Partition --> N1[("Node 1<br/>ZoneTree")]
     Partition --> N2[("Node 2<br/>ZoneTree")]
     Partition --> N3[("Node 3<br/>ZoneTree")]
 ```
 
-Each authenticated call gets its own Orleans request grain. Partition grains route to node-local storage owners; moving a grain does not move its storage handles. Writes require a persisted majority of the three replicas. See the [architecture map](docs/Architecture.md).
+Each authenticated call gets its own request grain, with bounded call-local data and no persisted request state. After the operation and its stream cleanup settle, it requests deactivation immediately instead of waiting for ordinary idle collection. Completed requests are not kept as a history of active grains. Actual activation and memory recovery under load still require qualification.
+
+Persistent connections will have a separate, bounded connection/session grain; that connection layer is still in development. Partition grains route to node-local storage owners; moving a grain does not move its storage handles. Writes require a persisted majority of the three replicas. See the [architecture map](docs/Architecture.md) and [grain lifetime contract](docs/Features/ClusterRouting/ExecutionPrimitives.md#connection-and-request-lifetimes).
 
 ## Why .NET, Orleans and ZoneTree
 

docs/ADR/ADR-065-full-sql-client-compatibility.md

@@ -65,6 +65,20 @@ family keeps the full SQL gate false. PostgreSQL wire3.0 is the first native
 client target, with explicit3.2 negotiation fixtures before advertising that
 version. Current HTTP/JSON plus official MCP remain their actual transports.
 
+Owner clarification 2026-10-09 requires a separate Orleans connection/session
+grain for each accepted persistent logical client connection. Its bounded
+disposable session state is distinct from a fresh state-free operation grain;
+request/read activations request DeactivateOnIdle after their original work and
+cleanup settle. [ClientApi connection requirements](../Features/ClientApi.md#persistent-connection-ownership)
+own REQ/AC-CLIENT-CONNECTION-001/002 and TASK-CLIENT-CONNECTION;
+[ClusterRouting lifetime requirements](../Features/ClusterRouting/ExecutionPrimitives.md#connection-and-request-lifetimes)
+own REQ/AC-ORL-013 and TASK-ORL-REQUEST-LIFETIME. Freeze actual connection identity,
+transport callbacks, typed quotas, scheduling, cancellation and joined teardown
+before integration. A session must reload current persisted authorization for
+each operation and cannot retain storage views, trusted roles or completed
+request history. Native-client/MCP interoperability and activation/RAM recovery
+remain unqualified; this decision does not advertise a delivered session layer.
+
 [Command inventory](../implementation/sql-client-commands-postgresql18.json)
 enumerates all183 entries from the official version18 command index. Family
 mapping is research inference;75 entries need explicit named coverage beyond

docs/Architecture.md

@@ -141,6 +141,14 @@ The [documentation index](README.md) is the complete entry point for 25 canonica
 
 Current mandatory policy requires an Orleans RF3 database, node-local PartitionHost storage ownership, separate request grains, distributed grain directory and activation migration, TUnit tests, Docker/Aspire RF3 execution and real .NET SDK plus official MCP SDK callers. Atomic partitions remain separate from physical replica placement. Credentials and trusted authorization are persisted server-side.
 
+Request/read grains are short-lived operation owners with no persisted request
+state; current settlement asks for native deactivation after original work and
+cleanup. Persistent connections require a separate bounded connection/session
+grain, still unimplemented. [Connection ownership](Features/ClientApi.md#persistent-connection-ownership)
+and [request lifetimes](Features/ClusterRouting/ExecutionPrimitives.md#connection-and-request-lifetimes)
+distinguish these contracts and retain the open real-client, activation-count,
+backlog and RAM qualification gates.
+
 Native Orleans execution/scheduling choices are mapped per grain and method in
 [ClusterRouting ExecutionPrimitives](Features/ClusterRouting/ExecutionPrimitives.md)
 and [ADR-110](ADR/ADR-110-native-orleans-execution-primitives.md). Bounded

docs/Features/ClientApi.md

@@ -61,6 +61,32 @@ CALL/unknown roots with genuine Kestrel tests; TASK-SQLC-FULL owns native client
 interoperability. [Inventory](../implementation/sql-client-conformance.json)
 keeps both native and full SQL qualification false until actual evidence exists.
 
+## Persistent connection ownership
+
+Owner clarification 2026-10-09 requires one Orleans connection/session grain
+for each accepted persistent logical client connection, separately from each
+short-lived request grain. Current HTTP operations and the official MCP transport
+do not establish that this session layer exists. Native SQL and persistent MCP
+session integration remain implementation targets under
+[ADR-065](../ADR/ADR-065-full-sql-client-compatibility.md); request cleanup is owned
+by [ClusterRouting](ClusterRouting/ExecutionPrimitives.md#connection-and-request-lifetimes).
+
+| Requirement | Measurable acceptance | Automated proof / current state |
+|---|---|---|
+| REQ-CLIENT-CONNECTION-001: an accepted persistent logical connection has one server-authenticated Orleans session identity and bounded disposable state; each operation retains its separate signed request identity and fresh persisted authorization. | AC-CLIENT-CONNECTION-001: real native SQL clients and official MCP clients where persistent sessions apply perform multiple operations through the same connection owner, while concurrent connections and requests have distinct isolated identities. Credential/policy revocation rejects the next operation and preserves stored state; reconnect obtains a fresh connection identity without recovering stale roles, payloads or results. | TASK-CLIENT-CONNECTION / planned ClientApi connection whole-flow tests and Aspire RF3 native-client/official MCP cases. No current implementation or passing evidence is claimed. |
+| REQ-CLIENT-CONNECTION-002: bound connection admission, retained state, in-flight work, disconnect/idle expiry and joined cleanup through validated typed options. | AC-CLIENT-CONNECTION-002: saturation has a fixed typed rejection without unbounded admission or buffers; disconnect/idle expiry cancels and joins original operations, releases session resources and requests native deactivation. Abrupt transport/silo loss, slow consumption and cancellation during cleanup preserve committed-write uncertainty and recover capacity within the frozen observation deadlines; native session activations return to baseline. | Same task and real transport/fault/lifecycle tests; exact numeric limits, protocol state, scheduling and teardown ownership must be frozen before implementation. Source/configuration alone is not acceptance. |
+
+ClientApi owns transport/session registration and lifetime; QueryExecution owns
+actual SQL statement/portal/transaction semantics. The connection grain owns no
+ZoneTree handles, quorum receipt or persisted credential authority. Root owns
+shared contracts and the integration join. Implement in order: freeze logical
+identity, transport ownership, quotas and audited per-method scheduling; author
+real client success/revocation/overload/disconnect/fault tests; implement session
+routing plus original cancellation/cleanup joins; then qualify the complete
+mapped Linux Aspire RF3 scope. Session routing must not serialize unrelated
+operations accidentally or introduce blanket reentrancy. Rollback is scoped
+source rollback before protocol qualification, with no data migration or fallback.
+
 REQ-CLIENT-010 / AC-CLIENT-010 / AC-DIAG-001..004 add bounded internal RF3
 dispatch evidence under [ADR-036](../ADR/ADR-036-orleans-foundation.md).
 Closed credential/read/command phases and failure categories correlate the

docs/Features/ClusterRouting/ExecutionPrimitives.md

@@ -30,6 +30,42 @@ The linked adoption contracts own executable stages and reader rollout.
 Frontend: N/A, no new UI. Client schemas: N/A for these stages; existing SDK/MCP
 operation contracts remain the qualification entry points.
 
+## Connection and request lifetimes
+
+Owner clarification 2026-10-09 distinguishes a persistent connection/session from
+an individual operation. [ClientApi](../ClientApi.md#persistent-connection-ownership)
+and [ADR-065](../../ADR/ADR-065-full-sql-client-compatibility.md) own the required
+connection grain and its bounded disposable session state. That layer is not
+implemented. A connection is not the storage owner or an authorization cache;
+every operation still has a fresh signed GUID and persisted authorization.
+
+The existing request and independently keyed read grains have no persisted
+request state. Payload, identity, reply and probe state must remain bounded and
+call-scoped, with no retained completed-request history, activation-owned storage
+handles, request timers or per-request caches. RequestGrain passes DeactivateOnIdle
+to NativeCqrsStreamLifetime; NativeCqrsStreamSettlement first awaits native
+producer disposal and then invokes that callback. DatabaseReadGrain requests the
+same deactivation in its capability finally. Success, rejection, failure,
+cancellation, deadline and early disposal must all settle original work before
+activation removal; a terminal frame alone is not completion of cleanup.
+
+[Native Orleans DeactivateOnIdle](https://learn.microsoft.com/en-us/dotnet/api/orleans.grain.deactivateonidle?view=orleans-10.0)
+requests removal when the activation becomes idle, overriding ordinary idle
+collection. This is asynchronous runtime deactivation, not synchronous CLR
+memory reclamation. Existing source proves the cleanup request, not measured
+activation-count or RAM recovery after a burst.
+
+The current validated GrainRoutingOptions admit at most 64 request producers and
+128 producer/capability frames per silo. Those are execution-frame bounds, not
+a bound on every activation awaiting creation, admission or deactivation.
+Ingress and cleanup backlogs therefore need their own bounded-flow proof.
+At stable load, concurrent requests are approximately completed requests/second
+times mean execution-plus-cleanup seconds; request/read activations and native
+transport overhead must be counted separately. For example, 10,000/s at 100 ms
+means roughly 1,000 concurrent requests before other overhead, not one retained
+activation for every historical request. This is arithmetic, not KeyLoad capacity
+or throughput evidence.
+
 ## Per-grain and method selection
 
 | Current owner / method | Decision and concrete reason |
@@ -68,6 +104,7 @@ Implementation authorized on 2026-10-06; concrete staged contracts are in
 | REQ-ORL-010: review all official documentation capability families for useful KeyLoad applications. | AC-ORL-010: a version-aware linked inventory covers grain/runtime model, messaging, state/time, services/lifecycle, placement/directory/migration, serialization, hosting/configuration, observability, security/deployment and testing/resources. Each capability records actual source presence, concrete use, missing contract and priority or deferral; unknowns and legacy examples stay explicit. | TASK-ORL-CAPABILITY-REVIEW; primary-source/native-API review plus actual source search and static link/navigation validation are the explicit documentation-only evidence exception. No runtime or performance result is inferred. |
 | REQ-ORL-011: wake the existing native due service from canonical apply with bounded, joined disposable waiting. | AC-ORL-011: actual apply/racing registration/coalescing/cancellation/shutdown workflows settle safely; at most two scan pages per second, one page/job in flight and unchanged finite sweep/creator/quorum/restart single-effect contracts pass through actual SDK/MCP operations. | TASK-ORL-DUE-APPLY and ROOT-JOIN in RuntimeAdoption; new real-operation ClusterReplication/Messaging cases and existing DueCoordination RF3 gates. |
 | REQ-ORL-012: export native Orleans runtime telemetry with bounded fail-closed privacy. | AC-ORL-012: real signed write/read/failure/concurrent identity operations preserve state/outcome and trace parentage; exported points/spans/exemplars contain only the accepted fixed metadata, immutable privacy sentinels suppress unsafe spans, capture/providers flush and join. | TASK-ORL-TELEMETRY/ROOT-JOIN in RuntimeAdoption; new OrleansRuntimeTelemetry operation cases plus actual SDK/MCP RF3 qualification. |
+| REQ-ORL-013: request/read activations are disposable operation lifetimes, with immediate native deactivation after joined cleanup and no retained completed-request state. | AC-ORL-013: real SDK and official MCP success, rejection, cancellation, deadline and early-disposal flows settle original producers/capabilities and preserve stored effects or stable uncertain outcomes. Native request/read activation counts return to the pre-trial baseline within the frozen observation deadline, shorter than ordinary idle collection; repeated bounded bursts do not increase that baseline. Saturation rejects before unbounded activation/admission/cleanup backlog, and a subsequent authorized operation succeeds without prior payload/identity/result crossover. | TASK-ORL-REQUEST-LIFETIME / root integration owner; existing NativeCqrsRequestV2 settlement/work-owner cases cover mechanisms. A dedicated real Aspire RF3 RequestActivationLifetimeRf3Tests scope, native activation observations and isolated Linux load/RAM evidence remain planned; source callbacks and ProducerDisposed markers alone do not pass this criterion. |
 
 Native scheduling still runs one turn at a time. Interleaving admits other turns
 while a method awaits; it does not parallelize a CPU loop. AlwaysInterleave can
@@ -133,6 +170,7 @@ flowchart LR
 |---|---|
 | TASK-ORL-AUDIT / read-only native API and grain reviewers | Inspect pinned version, official APIs and actual methods. Complete with source-backed findings; no source/provider/test edits. |
 | TASK-ORL-CONTRACT / root integration owner | Join both audits; own root policy, this specification, ADR-110, architecture/index/status links. Complete after policy diff preservation, link/diagram checks and static governance. This is the current stage. |
+| TASK-ORL-REQUEST-LIFETIME / root integration owner | First freeze native observation deadlines below ordinary idle collection and finite ingress/admission/cleanup bounds. Own matching ClusterRouting lifetime operation tests, any reproduced lifecycle repair and the Server admission join. Verify real stored outcomes and original cleanup, actual request/read activation return to baseline, saturation and following-operation isolation through Aspire RF3. Run heavy load/RAM trials only in isolated Linux GitHub jobs; no runtime gate closes from this documentation stage. |
 | TASK-ORL-WORKERS / ClusterRouting execution owner | Starts after exact pure operation, keys, quotas, call-graph transitions and oracle are frozen. Own new feature-local Grains/Contracts/Models and matching real-operation tests. No storage or request-grain replacement. |
 | TASK-ORL-CONTROL / native long-operation owner | Starts after NativeCqrs durable operation/control API and per-await state audit exist. Own only control contract and grain scheduling plus real identity/cancellation tests; public API changes require their owning ADR. |
 | TASK-ORL-HINTS / affected slice owner | Starts only when a concrete disposable hint and no-hint recovery path are frozen. Own that method and actual loss/duplicate/overload tests; no reliable protocol may be converted silently. |