PulseTrade.Comm.ResourceNode.DurableProxy 0.1.0-alpha42

PulseTrade.Comm.ResourceNode.DurableProxy

PulseTrade.Comm.ResourceNode.DurableProxy owns the RN-side durable proxy abstraction. It is not a public MCP server, not a GW route registry, and not a replacement for PTCS ActorFabric.

Purpose

RN.Host should be able to declare low-cognitive backend functions while this package owns the durable actor mechanics:

DurableProxy wraps those functions into ResourceNodeShardedFunctionSpec<'In,'Out> and owns retry, timeout/dead-letter, terminal completion, idempotency keying, Akka ClusterSharding placement, and ShardingDelivery confirm timing.

Current API

• ResourceNodeShardedFunctionSpec<'In,'Out>: full sharded function spec.
• ResourceNodeShardedFunctionActor.props: direct actor props for package tests and direct shard entities.
• ResourceNodeShardedFunctionActor coalesces simultaneous envelopes with the same immutable completion key onto one in-flight task. Identical retries receive the same terminal result; a conflicting command that reuses the key fails closed before a second native effect.
• ResourceNodeShardedFunctionRegion.startWithProps: direct Akka ClusterSharding region helper.
• ResourceNodeShardedFunctionRegion.startSpecWithConsumerController: Akka ClusterSharding region helper that uses the package-level ShardingConsumerController actor/factory seam.
• ResourceNodeShardedFunctionActor.propsWithShardingConsumerControllerStart: actor props that register with a ShardingConsumerController on PreStart.
• ResourceNodeShardingConsumerControllerFactory.props: official Akka ShardingConsumerController<ResourceNodeShardedFunctionEnvelope> props factory.
• ResourceNodeShardingProducerControllerFactory.props / start: official Akka ShardingProducerController<ResourceNodeShardedFunctionEnvelope> props factory and start-message helper for the producer/dispatch side that owns a shard region reference.
• ResourceNodeShardingProducerLoop: side-effect-free producer outbox reducer for dispatch enqueue, retry/redrain handoff rebuild, controller message creation, and confirmation state transition.
• ResourceNodeShardingProducerOutboxStore: producer outbox store contract with LoadState and AppendEvents; concrete PCSL and SQL Server providers live in adapter packages.
• ResourceNodeShardingProducerActor: package-owned producer actor seam that accepts ResourceNodeShardingProducerDispatchCommand, consumes official ShardingProducerController.RequestNext<ResourceNodeShardedFunctionEnvelope> demand, emits official MessageWithConfirmation<ResourceNodeShardedFunctionEnvelope>, and can redrain captured pending outbox state after actor stop/recreate.
• ResourceNodeTerminalCompletionProviderBinding: adapts ResourceResultProjectionProvider into ResourceNodeActorRuntime.TryReplayTerminalAsync and CompleteTerminalAsync.
• ResourceNodeTerminalCompletionProviderBinding.withBackendCompletionCallback: optional callback seam that receives the original ResourceCommand, terminal ResourceCommandReply, and canonical ResourceNodeBackendCompletionRequest after provider projection/replay and before ShardingDelivery confirmation.
• ActorArguRawStringDurableProxySpec / ActorArguJsonStringDurableProxySpec<'Input,'Reply>: low-cognitive legacy proxy helpers.

ActorArgu route modes

Both low-cognitive specs expose an explicit ActorArguRouteMode:

Use ActorArguRawStringDurableProxySpec.withCommandTargetResolver or the equivalent typed JSON builder to opt into generic routing. ActorArguCommandTargetResolver.exactMap is the safe default: it requires a nonblank target, exact-matches a finite map, and rejects unknown targets before cmd2cell or ivkLegacy. The package does not turn user input into arbitrary ActorSelection calls.

The resolved target identity participates in sharding entity and terminal completion keys. This prevents a repeated command id sent through the same proxy to two different targets from replaying the other target's completion. Public metadata reports the mode and a bounded identity strategy, not the raw actor address.

PTCS Add Actor Key platform adapter

ActorArguPlatformDispatchProvider is the PTC/RN implementation of the PTCS dispatch-provider SPI. It separates the developer-facing native actor contract from the internal PTCS proxy DTOs:

UI raw string
  -> ActorArguTargetCommand inside PTCS/provider boundary
  -> exact ActorArguPlatformTargetBinding
  -> fCell2.S raw string
  -> developer/RN native actor
  -> fCell2<string> reply
  -> ActorArguTargetReply inside provider boundary
  -> PTCS history/UI

The native actor used by direct Add Actor Key does not consume ActorArguTargetCommand/Reply and does not own retry/confirm. ActorArguPlatformDispatchRuntime.create always downgrades caller-supplied durability booleans and is therefore suitable only for explicitly labelled local/test composition. Production composition must use ActorArguPlatformDispatchRuntime.production, which requires a concrete PCSL/SQL Server producer outbox, a PCSL/SQL Server terminal completion provider, replay-before-produce, a backend completion callback, restart redrain, and dispatch functions that await terminal result query. ActorArguPlatformDispatchProvider.createProduction additionally requires package-issued production evidence; four caller-supplied true values can no longer fabricate production readiness.

Bindings are immutable and exact. A browser actor address is never converted into an unrestricted ActorSelection; unknown and duplicate bindings fail closed. Explicit Add Target Key continues to route to the visible proxy and uses the existing SpecBound or CommandTargetResolved semantics.

Native fCell2 serializer

ActorArguFCell2StringSerializer is the stable serializer for the first native protocol:

Both PTCS producer ActorSystem and RN native ActorSystem must include ActorArguFCell2StringSerialization.config(). PTC-VFY-025 verifies serializer selection and round-trip for scalar/table cells using their concrete F# union-case manifests.

ConsumerController.Delivery<ResourceNodeShardedFunctionEnvelope> is confirmed only after terminal completion. With a provider-bound ResourceNodeActorRuntime, the controller delivery path probes provider replay before decode, handler invocation, or projection; existing completion still emits ConsumerController.Confirmed.Instance without recomputing the legacy handler. If a backend completion callback is configured, callback failure prevents confirmation instead of fabricating a terminal task result. GW-T-084BE proves a host can use that callback to build ResourceNodeBackendCompletionRequest HTTP completion/query requests and POST them to the SPA Host result-vault origin before confirmation. The package test gate also stops and recreates the consumer actor, redelivers the same envelope, and verifies replay/confirm/handler-skip behavior.

The producer factory, producer outbox reducer, outbox store contract, and producer actor seam are intentionally package-owned but not GW-owned. RN.Host currently owns the consumer/shard-region side. PTCS Host or another dispatch-side process can use ResourceNodeShardingProducerControllerFactory, ResourceNodeShardingProducerLoop, ResourceNodeShardingProducerOutboxStore, and ResourceNodeShardingProducerActor against the RN shard region vocabulary without taking a dependency on GW route types. The current actor seam can load/append through the store contract; concrete PCSL and SQL Server adapters now provide replayable event stores. GW-T-084BC proves the first SPA Host dispatch-side adapter using this producer path against a live RN.Host catalog ShardingConsumerControllerRegion. ActorArguPlatformDispatchRuntime.production is the fail-closed composition boundary for reusing those stores and terminal providers; live shared-provider service proof remains a separate runtime gate.

ShardingProducerController.MessageWithConfirmation replies with a controller-owned confirmation sequence. ResourceNodeShardingProducerActor must not map that value to a locally generated delivery sequence; it confirms the oldest sent pending envelope FIFO and then persists the matching producer outbox confirmation. GW-T-084BD, PTC3-T-063P/Q, and PTC3-T-064B guard this behavior.

Journal / Snapshot / DB

DurableProxy itself does not select a database and does not create Akka.Persistence journal/snapshot tables. Its actors can call SaveSnapshot, so the host ActorSystem may need an Akka snapshot-store if that actor path is promoted to a persistent production runtime, but this package does not configure that store.

Durable state currently crosses DurableProxy through provider contracts:

• terminal result completion: ResourceResultProjectionProvider;
• producer outbox replay: ResourceNodeShardingProducerOutboxStore;
• concrete providers: PulseTrade.Comm.ResourceNode.Pcsl and PulseTrade.Comm.ResourceNode.SqlServer.

Current SQL table DDL lives in PulseTrade.Comm.ResourceNode.SqlServer/README.md. Current PCSL set layout lives in PulseTrade.Comm.ResourceNode.Pcsl/README.md.

Boundary With GW

GW uses handlerIn / handlerOut around public MCP/Web invocation and route keys.

RN DurableProxy uses CommandToCell / InvokeLegacy / LegacyReplyToCell around backend durable commands, role/typeName/entity placement, and legacy actor replies.

The shapes are similar, but the APIs are not interchangeable.

Remaining Runtime Work

Package-level direct shard regions, provider-bound region runtime, ShardingConsumerController actor/factory slices, ShardingProducerController factory/start contract, producer outbox redrain reducer, producer outbox store contract, concrete PCSL/SQL Server producer stores, producer actor demand/redrain seam, provider-bound ConsumerController delivery replay, restarted consumer-actor redelivery skip, RN.Host catalog ShardingConsumerController region startup, bounded ActorSystem restart replay through RN.Host controller-region + PCSL producer outbox, SPA Host RN ProducerController-backed DurableIngress adapter proof, RN terminal completion callback to SPA task-vault proof, and RN terminal callback over a real local SPA Host HTTP completion/query origin are implemented. Remaining runtime work is external PTCS.Host/split-service deployment wiring, deployed split-service completion origin verification, live ProcSupervisor/Windows-service service-window proof, live shared-provider proof, rolling update, and bounded long-running soak.