PulseTrade.Comm.Actor.Registry 0.1.0-alpha5

PulseTrade.Comm.Actor.Registry

PulseTrade.Comm.Actor.Registry is the low-dependency PTC actor lifecycle package introduced by RFC-PTC-0017.

The package owns:

• explicit ActorOfRegistered / registeredActorOf wrappers;
• register / unregister lifecycle events;
• terminated watcher support for classic Akka actors;
• sharding lifecycle vocabulary for region, proxy, and entity state;
• renderer-neutral ActorTreeDocument;
• deterministic ActorTreeMarkdown report generation;
• a small in-memory outbox helper for sink retry tests and bootstrap scenarios;
• an optional UTF-8 JSONL append/replay baseline for package-level restart tests.

The package does not reference PTCS, GW, RN, PTCS.Dynamic, or any host project. PTCS.Host is expected to subscribe to lifecycle events and project them into PCSL, /actors/api/snapshot, /sync/ws, IndexedDB refresh, and report APIs.

Journal / Snapshot / DB

This package does not use Akka.Persistence or SQL Server. It does not create Akka journal tables, snapshot-store tables, or SQL tables.

Durability status:

• 0.1.0-alpha3 is a package-level JSONL baseline plus machine-readable durability profile only.
• 0.1.0-alpha4 keeps that durability boundary and adds full transport address capture for ActorSystem.ActorOfRegistered / actor-context ActorOfRegistered callsites when the Akka system exposes a default address.
• It can append lifecycle events to a caller-selected file and replay them from a fresh store instance after process restart.
• It is not a production durable actor registry provider.
• It is not a persistent actor and does not configure akka.persistence.journal or akka.persistence.snapshot-store.
• Production non-volatile /actors truth is expected to come from PTCS.Host projection into PTCS PCSL/SQL-backed storage, plus the future durable outbox/provider work tracked by PTC3-071/072/076.

Current durable baseline:

• ActorRegistryFileJsonlStore.create <path> stores lifecycle events as UTF-8 JSONL.
• The verifier path is .pcsl/verify.ptcActorRegistryPackage/registry.jsonl.
• The caller owns the file path; there is no hardcoded database name.
• There is no current database name and no CREATE TABLE statement in this package.

Machine-readable profile:

let profile = ActorRegistryDurabilityProfile.fileJsonl true

profile.ProviderKey                 // "file-jsonl"
profile.LocalReplayCapable          // true when a path is configured
profile.UsesAkkaPersistence         // false
profile.CreatesAkkaJournalTables    // false
profile.CreatesAkkaSnapshotTables   // false
profile.UsesSqlServer               // false
profile.CreatesSqlTables            // false
profile.ProductionReady             // false

Reserved provider keys are pcsl and sql-server, exposed through ActorRegistryDurabilityProfile.reservedPcsl and ActorRegistryDurabilityProfile.reservedSqlServer. They are not implemented in this core package and return ProductionReady=false.

JSONL record shape is one ActorRegistryLifecycleEvent per line:

{
  "contractVersion": "ptc.actor-registry.lifecycle-event.v1",
  "eventId": "registered-0001",
  "eventKind": "Registered",
  "runtimeKind": "Actor",
  "systemName": "DemoSystem",
  "address": "akka://DemoSystem/user/worker",
  "fullPath": "/user/worker",
  "parentPath": "/user",
  "name": "worker",
  "status": "Active",
  "statusVersion": 1,
  "generation": "gen-1",
  "nodeId": "node-a",
  "role": null,
  "shardId": null,
  "entityId": null,
  "typeName": null,
  "tags": ["ptc"],
  "metadata": { "package": "demo" },
  "observedAtUtc": "2026-06-28T00:00:00.0000000+00:00"
}

SQL Server / PCSL projection providers are intentionally not embedded in this low-dependency package yet. Production PTCS.Host should project lifecycle events into its own PCSL/SQL-backed actor registry stream and materialized snapshot when that host slice is enabled. Do not treat the JSONL file as the production database.

Basic Usage

open System.Threading.Tasks
open Akka.Actor
open PulseTrade.Comm.Actor.Registry

let events = System.Collections.Concurrent.ConcurrentQueue<ActorRegistryLifecycleEvent>()

let sink : ActorRegistryEventSink =
    fun event ->
        events.Enqueue event
        Task.CompletedTask

let settings =
    ActorRegistrySettings.create sink
    |> ActorRegistrySettings.withTags [ "ptc"; "demo" ]

let system = ActorSystem.Create("Demo")
let props = Props.Create(fun () -> UntypedActor.Empty)

let registered =
    system.ActorOfRegistered(settings, props, "worker")

Use the wrapper deliberately. F# extension members do not override Akka.NET instance ActorOf; callsites must opt in by calling ActorOfRegistered or ActorRegistryActorOf.registeredActorOf.

Address behavior:

• ActorSystem.ActorOfRegistered, IActorContext.ActorOfRegistered, and IUntypedActorContext.ActorOfRegistered try to record actor.Path.ToStringWithAddress(system.AsInstanceOf<ExtendedActorSystem>.Provider.DefaultAddress), so PTCS /actors can distinguish PTCS/GW/RN nodes.
• The generic IActorRefFactory helper cannot always discover an owning actor system, so it may still record the local actor path. Use the ActorSystem or context overload when full transport address matters.

Documents

• doc/SDK_API.md describes the public SDK/API surface.
• doc/ActorArchitecture.md describes watcher, outbox, ActorTree, and sharding lifecycle boundaries.