Skip to content

AIFACTORY-FEAT-074: StudioRealtimeGateway: complete delivery

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Factory Studio (PF-14) · Increment I3 Studio · State elaborated · Route backend-developer · Build order 114 of 185 (Factory code)

StudioRealtimeGateway is the edge service of bounded context BC-29 (Experience Composition). The SignalR hub that pushes projection updates, notifications and run events to Studio sessions — subscriptions per session bounded by its scope, backed by the platforms' gRPC streams (operations projections, run events) and StudioNotificationService; an edge service that deploys alone (ADR-0028, BC-29). Its own repository is ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway.

Delivers StudioRealtimeGateway (complete)
Stubs DashboardService as contract-stub, completed in I4
Realizes adrs: ADR-0014
Requirements FR-10, FUX-04, FUX-07, NFR-01, NFR-02, XL-06
Depends on —
Sources model/services/factory-studio/StudioRealtimeGateway.yaml

Scenarios to trace (2, catalog): SCN-StudioRealtimeGateway-001 ✓, SCN-StudioRealtimeGateway-002 ✓

AIFACTORY-US-036: Live updates reach only the sessions allowed to see them

behavior · persona requester As a requester, I want live updates of the runs, notifications and shared views I am looking at, so that the screen stays current, and nobody receives updates outside their scope.

This is the integration PBI of the feature. StudioRealtimeGateway is the edge service of bounded context BC-29 (Experience Composition) that deploys alone (ADR-0028): a SignalR hub that pushes run events, notifications and shared-view changes to Studio sessions, with one RealtimeSubscription per session and stream, bounded by the scope of the session and held in the shared cache with the Redis backplane of Studio:Realtime:Backplane, so a client that loses its replica reconnects to another. It owns no table and publishes no event. A subscription is created only after StudioBff confirmed that the session may read the subject, and its filter never widens the scope of the session. The server contract Realtime.Subscribe takes an execution-scope-v1, whose schema admits no stream kind, filter, session id or last sequence; as an assumption to be confirmed, those travel on the SignalR negotiation outside the modelled request, and StudioBff declares no operation for the confirmation of a session; both points are reported as open questions. In I3 the stream bridge takes its run source from the platform run stream RunControlService/RunControl.WatchRun, because DashboardService, whose Operations.Subscribe and RunProjectionUpdated the model names as the source of run lists, arrives in I4 (D130, D131); its client is built against a contract stub of that stream, and the streams whose source is not delivered in I3 are answered as unavailable. Of the five consumed events the inbox registers NotificationCreated of StudioNotificationService and SavedViewChanged of StudioBff; RunProjectionUpdated of DashboardService and AlertFired and AlertResolved of AlertRuleService arrive in I4 and are not registered in I3. The behaviour is delivered by AIFACTORY-US-1369 (subscription within the scope of the session and the run timeline), AIFACTORY-US-1370 (push of notifications and tenant-shared views), AIFACTORY-US-1371 (resume, backpressure and recovery) and AIFACTORY-US-1372 (health); this PBI proves the end-to-end paths that cross StudioBff, RunControlService and StudioNotificationService. Repository: ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway, created by the repository checklist of feature repository-and-pipeline-conventions and scaffolded from the base template with the Factory profile.

Acceptance criteria

AC1 Given the repository ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway with the Factory profile, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the tests pass, the template version is recorded, a container image is published and both scenarios of model/scenarios/StudioRealtimeGateway.yaml have a passing test that names its id (ADR-0028).
AC2 Given a deployed I3 instance with StudioBff, RunControlService behind ControlPlaneApi and this gateway, and a second session of the project that has the run-detail screen open with a RunTimeline subscription, when a run is submitted through StudioBff/ForwardCommand to RunControlService/SubmitRun and the second session subscribes to it, then each state change of the run appears live in the run-detail timeline of the second session through RunControlService/RunControl.WatchRun, without a reload, and a session of another tenant receives nothing (FUX-04, ADR-0015).
AC3 Given the inbox of the service, when its registrations are listed, then StudioNotificationService/NotificationCreated and StudioBff/SavedViewChanged are registered with idempotency on the event id, no handler of an event whose producer arrives in I4 is registered, and the service publishes no event and owns no table (model/services/factory-studio/StudioRealtimeGateway.yaml).
AC4 Given the service starts with two replicas and the Redis backplane, when it runs, then the secret studio-signing comes from a key-vault reference, every subscription is filtered by the tenant of its session, and the metrics connectsoft.factory.studio.realtime_connections, connectsoft.factory.studio.realtime_push_latency and connectsoft.factory.studio.realtime_refreshes are emitted as modelled (NFR-10, model/services/factory-studio/StudioRealtimeGateway.yaml).
AC5 Given the same deployed instance with StudioNotificationService and a reviewer with an open session holding a Notifications subscription, when RunControlService/ApprovalRequested names the role of the reviewer in the project, then the reviewer's open session receives the push of StudioNotificationService/NotificationCreated without a reload, and the notification it names is listed and marked read through the routes StudioBff fronts (FUX-04, ADR-0015).
Traces: services StudioRealtimeGateway, StudioBff, StudioNotificationService, RunControlService
Traces: aggregates StudioRealtimeGateway/RealtimeSubscription
Traces: apis StudioRealtimeGateway/Realtime.Subscribe, StudioRealtimeGateway/RealtimeHealth, RunControlService/RunControl.WatchRun, RunControlService/SubmitRun, StudioBff/ForwardCommand
Traces: events StudioNotificationService/NotificationCreated, StudioBff/SavedViewChanged, RunControlService/ApprovalRequested
Traces: adrs ADR-0014, ADR-0015, ADR-0028
Traces: requirements FR-10, FUX-04
Relates: screens run-detail, my-work
Relates: nfrs NFR-01, NFR-10
Depends on AIFACTORY-US-1369, AIFACTORY-US-1370, AIFACTORY-US-1371, AIFACTORY-US-1372, feature:run-control-service, feature:control-plane-api, feature:studio-bff, feature:studio-notification-service, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:contracts-package, feature:component-observability-factory-conventions
Sources model/services/factory-studio/StudioRealtimeGateway.yaml, model/scenarios/StudioRealtimeGateway.yaml, docs/planes/experience/studio/services/studio-realtime-gateway/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-427 Create the repository ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway and scaffold it from the ConnectSoft.BaseTemplate template with the Factory profile implementation The repository exists by the repository checklist of feature repository-and-pipeline-conventions; the output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway with the Factory profile from the pinned template package is committed unchanged, the repository records the template version, the solution builds and the template tests pass in the repository pipeline, which publishes the container image. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-428 Domain model: RealtimeSubscription implementation The aggregate holds the fields and the invariants of the model: a subscription exists only after StudioBff confirmed the session may read the subject and its filter cannot widen the scope of the session, and a reconnect resumes from the last sequence while a gap beyond the buffer requests a full refresh; unit tests cover every invariant. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-429 API hosting skeleton: the SignalR hub, Realtime.Subscribe and RealtimeHealth implementation The SignalR hub accepts connections with JWT validation and the scope factory.studio.use and reads the stream kind, the filter, the session id and the last sequence from the SignalR negotiation, outside the modelled request, as an assumption to be confirmed; the server contract Realtime.Subscribe is hosted with execution-scope-v1 requests and run-event-envelope-v1 stream items and its proto document, and RealtimeHealth is hosted on GW-01 under factory.health.read; the behaviour of each operation is delivered by AIFACTORY-US-1369 and AIFACTORY-US-1372, not here. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-430 Messaging skeleton: inbox of 2 of the 5 consumed events and no outbox implementation The inbox registers NotificationCreated of StudioNotificationService and SavedViewChanged of StudioBff with idempotency on the event id; RunProjectionUpdated, AlertFired and AlertResolved, whose producers arrive in I4, are not registered; the service has no outbox because it publishes no event. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-431 Worker hosting: StreamBridge with its retry policy, partitioning and idempotency key implementation StreamBridge is hosted with the retry policy exponential (10 attempts, 5 s backoff), at most sixteen in parallel partitioned by TenantId and the idempotency key subscriptionId plus sequence, so a duplicate upstream message is pushed once; its run source in I3 is RunControl.WatchRun and its client of Operations.Subscribe is a contract stub until I4. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-432 Security, tenancy and telemetry of StudioRealtimeGateway implementation Scopes and roles of the model are enforced, every subscription is filtered by the tenant of its session, the secret studio-signing comes from a key-vault reference, the backplane is configured from Studio:Realtime:Backplane, and the three realtime metrics, traces and health checks follow the observability conventions. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-748 Verify studio-realtime-subscriptions by running the scenario acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario~SCN-StudioRealtimeGateway" in the pipeline of ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway; a filter that discovers no test counts as a failure; it passes and proves the scenario part of AC1 of AIFACTORY-US-036, a passing test for SCN-StudioRealtimeGateway-001 and SCN-StudioRealtimeGateway-002. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5512 Verify the build, the single scaffold, the template version and the published image of StudioRealtimeGateway verification A pipeline run of ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway on its main branch passes dotnet build -c Release and dotnet test -c Release --no-build, its run record names the recorded template version and the digest of the published container image, and the repository history holds one scaffold commit; that record is the evidence of the build, scaffold and publication part of AC1 of AIFACTORY-US-036. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5513 Verify the inbox registrations, the secret, the tenant filter and the metrics of StudioRealtimeGateway verification Run dotnet test -c Release --filter "Category=Registration\|Category=Telemetry"; a zero-match filter counts as a failure; the tests compare the inbox registrations with model/services/factory-studio/StudioRealtimeGateway.yaml, check that no outbox and no table exist, the key-vault reference of studio-signing, the tenant filter of subscriptions on two replicas with the backplane and the three metrics, proving AC3 and AC4 of AIFACTORY-US-036. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5514 Verify the end-to-end run timeline and the approval notification push on a deployed instance verification Run dotnet test -c Release --filter "Category=EndToEnd" against a deployed I3 instance with StudioBff, RunControlService behind ControlPlaneApi, StudioNotificationService and this gateway; a zero-match filter counts as a failure; the tests submit a run through StudioBff ForwardCommand and watch it live in the run-detail timeline of a second session, and push the NotificationCreated of an approval to the open session of the reviewer, which lists and marks it read through StudioBff, proving AC2 and AC5 of AIFACTORY-US-036. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway

AIFACTORY-US-1369: Subscribe a session to a stream inside its scope and follow a run timeline live

behavior · persona requester As a requester, I want to subscribe the screen I look at to the stream of my run, so that each state change of the run reaches me without a reload, and a stream I may not read is refused.

A Studio client connects to the SignalR hub of StudioRealtimeGateway with the user token carrying factory.studio.use and the id of its active Studio session, and for each stream the hub negotiates the subscription through the server contract StudioRealtimeGateway/Realtime.Subscribe. The modelled request of that method is an execution-scope-v1, which names the tenant and the project of the session and whose schema admits no other field; the StreamKind, the filter (run id, project, environment or product), the session id and the last sequence therefore travel on the SignalR negotiation outside the modelled request, an assumption to be confirmed and reported as an open question. The gateway asks StudioBff whether the session may read the subject and records a RealtimeSubscription with its filter, its upstream and lastSequence only after StudioBff confirmed it; the filter can never widen the scope of the session. StudioBff declares no gRPC method for that confirmation, so the call has no modelled StudioBff operation, it is proven against a fake, and the gap is recorded as an open question. In I3 the stream kinds RunTimeline, Notifications and SavedViews are served: a RunTimeline subscription makes the stream bridge open RunControlService/RunControl.WatchRun with a run-ref-v1 for the run of the filter and the gateway's workload identity, and every run-event-v1 it receives is pushed as a run-event-envelope-v1 with the next sequence until the client unsubscribes, the run is terminal or the session ends. The kinds RunList and Approvals need the operations streams of DashboardService across a scope (I4), Alerts needs AlertRuleService (I4) and Rollout and Incident need the fleet services (I7); a subscription to any of them is answered UNAVAILABLE with the name of the missing source, and the screen shows that state. While StudioBff cannot be reached a new subscription is refused with UNAVAILABLE, because the confirmation is fail-fast, and the subscriptions already open keep receiving pushes. A missing or invalid token is refused with UNAUTHENTICATED; a token without factory.studio.use, a session StudioBff does not confirm or a filter that would widen the scope with PERMISSION_DENIED; an invalid negotiation with INVALID_ARGUMENT; and a run that does not exist or belongs to another tenant with NOT_FOUND, given alike for both (D113). A refused subscription records nothing. The side-effect class of the method is read.

Acceptance criteria

AC1 Given a session confirmed by StudioBff for a run in its project, when the hub negotiates a RunTimeline subscription through StudioRealtimeGateway/Realtime.Subscribe with the execution-scope-v1 of the session and, on the SignalR negotiation, the stream kind, the run id and the session id, then a StudioRealtimeGateway/RealtimeSubscription is recorded with the filter and lastSequence, RunControlService/RunControl.WatchRun is opened for that run, and each run-event-v1 is pushed as run-event-envelope-v1 with an increasing sequence until the run is terminal or the client unsubscribes (SCN-StudioRealtimeGateway-002, FUX-04).
AC2 Given a missing token, a token without factory.studio.use, a session StudioBff does not confirm, a filter wider than the scope of the session or a negotiation that fails validation, when StudioRealtimeGateway/Realtime.Subscribe is called, then it is refused with UNAUTHENTICATED, PERMISSION_DENIED or INVALID_ARGUMENT and no subscription is recorded; while StudioBff cannot be reached a new subscription is refused with UNAVAILABLE and open subscriptions keep receiving pushes (SCN-StudioRealtimeGateway-002).
AC3 Given a run that does not exist and a run of another tenant, when a RunTimeline subscription names each, then both are refused with NOT_FOUND, the status RunControlService/RunControl.WatchRun gives for both, and the answer never confirms that the foreign run exists (SCN-StudioRealtimeGateway-002, D113).
AC4 Given the kinds RunList, Approvals, Alerts, Rollout and Incident, whose sources are not delivered in I3, when a session subscribes to one of them through StudioRealtimeGateway/Realtime.Subscribe, then the subscription is answered UNAVAILABLE with the name of the missing source, nothing is recorded, and the screen shows the stream as unavailable (SCN-StudioRealtimeGateway-002, FUX-04).
Traces: services StudioRealtimeGateway, StudioBff, RunControlService
Traces: aggregates StudioRealtimeGateway/RealtimeSubscription
Traces: apis StudioRealtimeGateway/Realtime.Subscribe, RunControlService/RunControl.WatchRun
Traces: descriptors execution-scope-v1, run-ref-v1, run-event-v1, run-event-envelope-v1
Traces: adrs ADR-0015
Traces: requirements FUX-04
Traces: scenarios SCN-StudioRealtimeGateway-002
Relates: screens run-detail
Relates: nfrs NFR-01
Depends on feature:run-control-service, feature:studio-bff
Sources model/services/factory-studio/StudioRealtimeGateway.yaml, model/services/control-plane/RunControlService.yaml, docs/reference/schemas/execution-scope.schema.json, docs/planes/experience/studio/services/studio-realtime-gateway/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-525 Hub with subscriptions bounded by the session scope implementation A subscription is negotiated through Realtime.Subscribe with the execution-scope-v1 of the session and the stream kind, filter, session id and last sequence of the SignalR negotiation, recorded only after StudioBff confirmed the session for the subject, and refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND or UNAVAILABLE without a record; the filter cannot widen the scope of the session; an unreachable StudioBff refuses new subscriptions only. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-526 Stream bridge from RunControl.WatchRun to the RunTimeline subscriptions implementation The bridge opens RunControl.WatchRun with run-ref-v1 for each run with an open RunTimeline subscription, pushes every run-event-v1 as run-event-envelope-v1 with the next sequence to the subscribed connections, ends at the terminal state of the run, passes NOT_FOUND through and answers the kinds whose source is not delivered in I3 with UNAVAILABLE naming the source. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5499 Fakes of the session confirmation of StudioBff and of RunControl.WatchRun fixture The acceptance suite holds a fake session confirmation, standing for the StudioBff operation the model does not declare, that answers confirmed, refused and unavailable, and a fake RunControl.WatchRun endpoint that streams run-event-v1 items, ends at a terminal state, drops on demand and answers NOT_FOUND for an unknown and a foreign run. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5500 Verify subscriptions and the run timeline through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-StudioRealtimeGateway-002"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1369 against the fakes of AIFACTORY-TASK-5499. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway

AIFACTORY-US-1370: Push a new notification and a changed tenant-shared view to the sessions allowed to see them

behavior · persona reviewer As a reviewer, I want a new notification and a changed shared view to appear in my open Studio without a reload, so that I see an approval waiting for me as soon as it exists.

The inbox of StudioRealtimeGateway consumes two events, each idempotent on its event id. On StudioNotificationService/NotificationCreated the handler PushNotification pushes the notice to the connections of the sessions of the named user in the named tenant that hold a Notifications subscription, with its notificationId, kind and importance; the content of the notification is read by the client from StudioNotificationService through StudioBff, never from the push. On StudioBff/SavedViewChanged the handler PushViews can filter only by what the event carries: its payload holds viewId, tenantId, screenId and sharedWith, and neither the payload nor the envelope names the owner or the project of the view. The handler therefore pushes the change of a view shared with the tenant to the connections of that tenant with a SavedViews subscription for the screenId, and pushes no change of a private view or of a view saved with sharedWith project, which StudioBff treats as private (AIFACTORY-US-037); those reach their owner when the screen is opened. That SavedViewChanged needs the owner and the project of the view before such pushes can be filtered is reported as an open question. A push never reaches a session of another user for a notification and never a session of another tenant (ADR-0015). A redelivered event is pushed once, because the push is keyed by the subscription and the sequence. A session without an open connection receives nothing from the push; it reads the current state when it opens the screen. The gateway writes nothing and publishes nothing.

Acceptance criteria

AC1 Given two open sessions of the user named by StudioNotificationService/NotificationCreated with a Notifications subscription, and a session of another user, when the event is consumed, then both sessions of the user receive the push with notificationId, kind and importance, and the other user receives nothing (ADR-0015).
AC2 Given StudioBff/SavedViewChanged for a view shared with the tenant and another for a private view, when they are consumed, then the sessions of that tenant with a SavedViews subscription for that screenId receive the change of the tenant-shared view, no session receives the change of the private view, and sessions of other tenants receive nothing (model/services/factory-studio/StudioRealtimeGateway.yaml).
AC3 Given the same event delivered twice, when it is consumed again, then no session receives a second push for it (StudioNotificationService/NotificationCreated, StudioBff/SavedViewChanged).
Traces: services StudioRealtimeGateway, StudioNotificationService, StudioBff
Traces: aggregates StudioRealtimeGateway/RealtimeSubscription
Traces: events StudioNotificationService/NotificationCreated, StudioBff/SavedViewChanged
Traces: adrs ADR-0015
Traces: requirements FUX-04
Relates: screens my-work, approvals-list
Relates: nfrs NFR-01
Depends on feature:studio-notification-service, feature:studio-bff
Sources model/services/factory-studio/StudioRealtimeGateway.yaml, model/services/factory-studio/StudioBff.yaml, docs/planes/experience/studio/services/studio-realtime-gateway/index.md#messages

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-5501 PushNotification and PushViews inbox handlers implementation PushNotification pushes NotificationCreated to the connections of the named user with a Notifications subscription in the named tenant; PushViews pushes SavedViewChanged of a tenant-shared view to the connections of that tenant with a SavedViews subscription for the screen and pushes nothing for a private or project-shared view, whose owner and project the event does not carry; both are idempotent on the event id and push nothing to another user or tenant. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5502 Verify the pushes of notifications and shared views verification Run dotnet test -c Release --filter "Category=Acceptance&Category=Push"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1370 with published NotificationCreated and SavedViewChanged events, tenant-shared and private views and sessions in and out of scope. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway

AIFACTORY-US-1371: Resume a dropped stream from the last sequence, refresh after an overflow and close ended sessions

behavior · persona requester As a requester, I want a dropped connection or upstream stream to resume without a gap, so that the run I follow shows every state, and the screen refreshes rather than skipping silently.

Each RealtimeSubscription keeps the last sequence delivered and a buffer of Studio:Realtime:BufferPerConnection messages (500 by default). When a client reconnects, on the same replica or on another through the backplane, it resubscribes through StudioRealtimeGateway/Realtime.Subscribe and names its last sequence on the SignalR negotiation, outside the modelled execution-scope-v1 request (the assumption of AIFACTORY-US-1369), and resumes from there; when the gap is larger than the buffer, the gateway asks the client for a full refresh of the screen, which reads the current state through StudioBff/GetScreenModel, and counts it in connectsoft.factory.studio.realtime_refreshes; a gap is never skipped silently (invariant of RealtimeSubscription). A connection whose buffer fills is marked under backpressure and receives a full-refresh request rather than a partial stream. When the upstream RunControlService/RunControl.WatchRun drops, the stream bridge reconnects with exponential backoff under its retry policy (10 attempts, 5 s) and resumes from the last sequence it pushed, idempotent on the subscription and the sequence so nothing is pushed twice; when the retries are exhausted, every affected connection receives a full-refresh request and the upstream is reported unhealthy by StudioRealtimeGateway/RealtimeHealth. A subscription is closed when its client unsubscribes or disconnects. The model names no notice from StudioBff to the gateway when SessionSweeper expires a session, so the gateway is never told: a subscription of an expired session stays open and keeps receiving pushes until its next confirmation, on a reconnect or a resubscription, which StudioBff refuses for the expired session, and the subscription is then closed. This PBI sets no bound on how long an expired session can keep receiving pushes; that bound is left explicitly to the open question.

Acceptance criteria

AC1 Given a session that received sequence 40 of a run timeline and reconnected through another replica, when it resubscribes through StudioRealtimeGateway/Realtime.Subscribe naming its last sequence on the negotiation and the gap is within the buffer, then it receives 41 onwards with no gap and no duplicate (model/services/factory-studio/StudioRealtimeGateway.yaml, FUX-04).
AC2 Given a gap larger than Studio:Realtime:BufferPerConnection or a connection whose buffer filled, when the gateway detects it, then the client receives a full-refresh request, reads the current state through StudioBff/GetScreenModel, and connectsoft.factory.studio.realtime_refreshes counts it (model/services/factory-studio/StudioRealtimeGateway.yaml).
AC3 Given RunControlService/RunControl.WatchRun drops, when the stream bridge reconnects within its retry policy, then the subscription resumes from the last sequence pushed and no item is pushed twice; when the retries are exhausted, every affected connection receives a full-refresh request and the upstream is reported unhealthy (StudioRealtimeGateway/RealtimeHealth, XL-06).
AC4 Given a client that unsubscribes or disconnects, when the gateway handles it, then the subscription is closed and no further push reaches it; given a session expired by StudioBff whose client reconnects or resubscribes, when StudioBff refuses its confirmation, then its subscriptions are closed, while before that confirmation no bound is set (StudioRealtimeGateway/Realtime.Subscribe, FR-10).
Traces: services StudioRealtimeGateway, StudioBff, RunControlService
Traces: aggregates StudioRealtimeGateway/RealtimeSubscription
Traces: apis StudioRealtimeGateway/Realtime.Subscribe, StudioRealtimeGateway/RealtimeHealth, StudioBff/GetScreenModel, RunControlService/RunControl.WatchRun
Traces: requirements FR-10, FUX-04, XL-06
Relates: screens run-detail
Depends on feature:run-control-service, feature:studio-bff
Sources model/services/factory-studio/StudioRealtimeGateway.yaml, docs/planes/experience/studio/services/studio-realtime-gateway/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-527 Release of subscriptions on session end implementation Subscriptions are closed when the client unsubscribes or disconnects and when StudioBff refuses the confirmation of the session of a reconnecting or resubscribing client, so an expired session receives no further push after its next confirmation. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5503 Resume from the last sequence, buffer overflow refresh and upstream reconnect implementation A resubscription that names its last sequence on the negotiation resumes within the buffer of Studio:Realtime:BufferPerConnection, a larger gap or a full buffer sends a full-refresh request counted in realtime_refreshes, and a dropped RunControl.WatchRun is reconnected with exponential backoff and resumed from the last sequence; exhausted retries send full-refresh requests and mark the upstream unhealthy. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5504 Verify resume, refresh and recovery through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Category=Recovery"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1371 with two replicas on the backplane, the fake RunControl.WatchRun of AIFACTORY-TASK-5499 dropping on demand and the fake confirmation refusing an expired session. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway

AIFACTORY-US-1372: Report the liveness, readiness, connections and upstream health of the realtime gateway

behavior · persona operator As an operator, I want the realtime gateway to report its readiness, its open connections and the health of each upstream stream, so that I see at once whether live updates can flow and which source is missing.

An operator or the platform probe calls StudioRealtimeGateway/RealtimeHealth on the internal route GW-01 with a token that carries factory.health.read. The answer gives liveness, readiness, the number of open connections (connectsoft.factory.studio.realtime_connections) and the health of each upstream: StudioBff, which the confirmation of every new subscription requires (fail-fast); the backplane of Studio:Realtime:Backplane; the run streams of RunControlService, an optional dependency in degrade mode; and the operations streams of DashboardService, reported as not delivered until I4. The response is 200 while the gateway is ready. An upstream in degrade mode that drops is listed degraded and the response stays 200, because live updates of the other streams continue. While StudioBff is unreachable it is listed degraded and the response stays 200: new subscriptions are refused, but the subscriptions already open do not need StudioBff to keep pushing, and a 503 would take every replica out of rotation and drop them. Only while the backplane is unreachable is the gateway not ready, because subscriptions can no longer be shared across replicas, and it answers 503 with a problem response that names the backplane. A request without a token is refused with 401 and a token without factory.health.read with 403. Nothing is written by the probe.

Acceptance criteria

AC1 Given a ready gateway with open connections, when StudioRealtimeGateway/RealtimeHealth is called with factory.health.read, then the response is 200 with liveness, readiness, the connection count and the health of StudioBff, the backplane, the run streams of RunControlService and the operations streams shown as not delivered until I4 (SCN-StudioRealtimeGateway-001).
AC2 Given the run stream of RunControlService has dropped, or StudioBff is unreachable, when StudioRealtimeGateway/RealtimeHealth is called, then that upstream is listed degraded, the response stays 200, open subscriptions keep receiving pushes and, for StudioBff, new subscriptions are refused (SCN-StudioRealtimeGateway-001).
AC3 Given the backplane is unreachable, when StudioRealtimeGateway/RealtimeHealth is called, then the response is 503 with a problem response that names the backplane and no state changes (SCN-StudioRealtimeGateway-001).
AC4 Given a request without a token, or with a token that lacks factory.health.read, when StudioRealtimeGateway/RealtimeHealth is called, then the response is 401 or 403 respectively with a problem response, and no health detail is returned (SCN-StudioRealtimeGateway-001, ADR-0015).
Traces: services StudioRealtimeGateway
Traces: apis StudioRealtimeGateway/RealtimeHealth
Traces: adrs ADR-0015
Traces: requirements FUX-04
Traces: scenarios SCN-StudioRealtimeGateway-001
Relates: nfrs NFR-10
Sources model/services/factory-studio/StudioRealtimeGateway.yaml, docs/planes/experience/studio/services/studio-realtime-gateway/index.md#metrics-and-observability

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-5505 RealtimeHealth with connections and upstream health implementation RealtimeHealth reports liveness, readiness, the open connection count and the health of StudioBff, the backplane, the RunControlService run streams and the DashboardService operations streams marked not delivered until I4; it stays 200 with StudioBff or an optional upstream listed degraded, answers 503 naming the backplane only while the backplane is unreachable, and refuses a request without a token with 401 and one without factory.health.read with 403. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway
AIFACTORY-TASK-5506 Verify the health probe through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-StudioRealtimeGateway-001"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1372. ConnectSoft.AI.SoftwareFactory.StudioRealtimeGateway