PulseTrade.Comm.ResourceNode.DurableProxy 0.1.0-alpha2

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.
• 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.

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, but live shared-provider service proof remains a separate runtime gate.

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.