07 — Services Catalog#

Who this is for. Anyone looking for "where does X live?" or "is there already something that does this?" before writing a new service.

What you'll learn. A guided index to everything under Ring/Services/ — each entry a short, verified statement of responsibility and its key collaborators, with its file path. Entries are grouped by concern rather than by directory where that reads better; the directory is always given.

How to read this. Each summary was taken from the type's own doc comment in the cited file. Where a service's own comment states a limit, a rationale or a warning, this catalog carries it — those are the parts that stop you reintroducing a fixed bug. Where a service is large enough to need its own explanation, this chapter points at the chapter that gives it.

Coverage. Every .cs file directly under Ring/Services/ and in each of its fifteen subdirectories is named somewhere below. Interfaces and their default implementations are grouped together; small companion types (enums, records, option objects) are named with the service that owns them rather than given their own row. Nothing under Ring/Services/ is silently omitted — if you cannot find a file here, that is a defect in this chapter. This catalog is Services-only; the equivalent catalog for Ring/ViewModels/ is chapter 06 §6.1a.

The PLC services are catalogued here only briefly; chapters 03 and 04 are their real documentation.

7.1 PLC — Ring/Services/PLC/#

The largest subfolder and essentially flat. Grouped by role:

Gates and write infrastructure#

Writers#

Pollers, snapshots and caches#

PlcPollingCoordinator.cs owns seven pollers, each publishing an immutable snapshot into a static holder or cache:

RosterPollPlan.cs is the pure roster→read-target translation. Cadences and gotchas: §3.2.

Readers and decoding#

PlcTagReader.cs (+ IPlcTagReader.cs, PlcDataType.cs) is the per-tag reader; UdtTankReader.cs + UdtTankLayout.cs are the byte-offset UDT path. Per-subsystem readers: StorageTankTagReaderService, UseTankTagReaderService, TVCTagReaderService, BatchTagReaderService, InventoryStampsPlcReader. Index maps: PcReadIndexes.cs, PcWriteIndexes.cs. Decoders: SystemStatusWord.cs (the PC_Read_Integer[9] hold/running word and the Process-menu command policy), BatchOperationMapper.cs (operation code → description), IngredientFamilyMapper.cs (operation codes → coarse ingredient families), BatchStamps.cs (element indexes inside Batch_Current_Stamps), AgitatorPresetBands.cs (the single definition of the agitator preset minute bands).

Diagnostics and demo#

7.2 Alarms — Ring/Services/Alarms/#

An alarm, controller → operator#

The pieces below are each independently correct but never sequenced elsewhere in this book. This is the path a single alarm actually takes, verified against the sources:

1. Acquisition. Two independent 2 s timers reach the same call — MainWindow's _plcUpdateTimer DispatcherTimer and a background System.Threading.Timer alarm pump (PlcAlarmBackgroundPumpInterval, MainWindow.xaml.cs:170) — both routed through RequestPlcAlarmPollAndPopups(), which throttles the actual PLC read to no more than once per PlcAlarmPollMinGap = 8 s (MainWindow.xaml.cs:164) and busy-gates the two callers so they never race. That reaches AlarmAlarmNumberPlcService.PollAlarmsForPopupsAndCache() (:578-629), which bulk-reads Alarm_Alarm_Number as INT[40] in one PLC read (:162-171), falling back to 40 individual indexed reads only if the bulk decode fails (:211-244) — the point being to avoid a 40× timeout storm on the common path.
2. Decode. AlarmNumberDecoder.DecodeBaseAlarmNumber (:101-112) strips the band offset to get the catalog number; DecodeState (:114-128) classifies the raw value as Active (1–999), a silenced fault still present (1000–1999) or a resolved, cleared fault (2000–2999).
3. Describe. AlarmDescriptionBuilder.BuildDescriptionOrError (:49-63) looks the catalog number up in the AlarmDefinitions table, substituting a computed tank number where the definition's HasTankIndex says to; an uncatalogued number gets a localizable "Alarm {N}" placeholder rather than a blank (:71-75).
4. Timestamp, where legacy PLC date parts are used. AlarmLegacyDateTime.FromPlcParts (:27-65) reconstructs a full DateTime from the PLC's month/day/hour/minute/second (it supplies no year, so the year is inferred from the PC clock with a rollover rule); AlarmLifecycleTimeParser.TryParseDisplayToUtcIso (:11-44) is the inverse, parsing a grid-displayed string back to UTC ISO for storage.
5. Persist and time-track. AlarmAlarmNumberPlcService.RecordPlcAlarmEventsIfEnabled (:768-938) reconciles the whole snapshot into the lifecycle repository and inserts one PlcAlarmEvents row per identity transition. PlcAlarmUiTimingStore.ApplySnapshot (:129-200) separately tracks each slot's raised/acknowledged/resolved times in memory — carrying a base alarm's original raise time across the PLC's own shift-insert queue moving it to a different slot — and rehydrates from persisted events at startup (HydrateFromEvents, :212-258) so a restart cannot fake-reset an alarm's displayed age.
6. Present. AlarmSummaryComposer.Compose (:44-74) splits rows into shelved (suppressed) versus visible and sorts both by severity then recency for the ISA-101 Alarm Summary screen — display-only, and never a factor in detection, logging or escalation (:9-16). AlarmScreenLinkResolver.Resolve (:106-130) maps the catalog number to a deep link into the relevant equipment screen; a plant-wide alarm deliberately resolves to None because no single screen owns it. PlaybookService.GetByAlarmNumber (:105-147) returns the first-response Meaning/FirstCheck/WhoToCall entry, optionally overridden per alarm from the database.
7. Escalate. A newly-raised alarm fires IAlarmEscalator.NotifyAsync (AlarmAlarmNumberPlcService.cs:1090-1125). The default is NoopAlarmEscalator, which only logs a "would notify" line — active until AlarmEscalation.Mode is switched to "Smtp" or "Webhook". Independently of escalation, rule-driven alarm emails are gated per rule by AlarmEmailStormControl.Register (:55-88), which returns SendSingle, SuppressedByCooldown or Digest so a flood collapses into one email rather than one per event; a severity-aware check against SmtpAlarmEscalator.WouldSend stops the rule engine and the SMTP escalator from both emailing the same raised alarm.
8. Silence — the one write in this pipeline. Everything above is reads and local state. Silencing an alarm is an operator-initiated write, covered on the write path in chapter 04 §4.7, not repeated here.

The catalog, by role#

Acquisition and decoding.

The silence write.

Presentation and triage.

Notification and escalation.

Analytics.

7.3 Audit — Ring/Services/Audit/#

7.4 Batch — Ring/Services/Batch/#

Batch policy types (eligibility, preconditions, split mapping) live with the screens in Ring/Views/BatchStart/ — see chapter 06 §6.3.

7.5 Display — Ring/Services/Display/#

Ring/Services/PlantNativeUnits.cs (top level) is the single declaration of this site's native recipe/batch weight unit and the display seam every consumer goes through — read it together with docs/production-readiness/RECIPE_UNITS_VERDICT_2026-07-31.md, which settled the question: pounds.

7.6 Reports — Ring/Services/Reports/#

The largest non-PLC subfolder. Three layers, and it is worth keeping them separate when you add one.

Pure calculators (no I/O, no PLC, no UI, fully testable):

Read-only query services (assemble a payload from persisted data only):

Document builders (FlowDocument for on-screen preview and PrintDialog output — each pairs with the report screen of the same name in chapter 06 §6.3): BatchReportDocument, BatchHistoryReportDocument, BatchHistoryUsageReportDocument, UsageReportDocument, CostsReportDocument, FormulaReportDocument, GlueUsageReportDocument, InventorySnapshotReportDocument, ShiftHandoverReportDocument, YieldGiveawayReportDocument, DataEntryReportDocument. PdfExportService renders any of them to PDF.

Scheduling: ReportSchedulerService (1-minute timer over subscriptions) + ScheduledReportRenderer.

And one small type that carries a contract: ReportDataUnavailableNotice.cs — the single wording used everywhere a report surface has to say "this is not a zero, the data could not be read". It is the user-facing half of RepositoryReadScope (§5.2).

7.7 Email and notifications#

Ring/Services/Email/ — IEmailDeliveryService / EmailDeliveryService.cs is the shared SMTP transport for the whole app: Enqueue drops the message on an in-memory BlockingCollection and returns immediately, so a dead or slow SMTP server can never block the UI thread; a background worker sends with a 3-attempt retry (1s/2s/4s backoff).

Durable-by-construction queue. Enqueue writes a Status='Pending' EmailLog row (IEmailLogRepository) synchronously, before the message ever touches the in-memory queue. The worker updates that same row to Sent or Failed when the send finishes, with the full exception text on failure. This means a dead SMTP server degrades to visible log rows, never a frozen HMI or a silently vanished message.

Crash / power-cut recovery — and why it never auto-resends. A process death after the pending row is written but before the worker finishes leaves that row stuck at Status='Pending'. On the next startup, RecoverPendingFromPriorRun sweeps every such row and marks it Failed with reason "recovered after restart…" — it is deliberately never resent, because this service cannot tell whether the original attempt actually left the wire, and a duplicate alarm/report email is judged a worse failure mode than a documented gap the operator can act on. Documented residual: the one window this doesn't cover is a crash during the few seconds DatabaseWriterQuiesce/SuspendDelivery holds the database file for a restore or factory reset — a message queued in that narrow window has no durable row to recover, so it degrades to in-memory-only for that one message. Outside a crash, SuspendDelivery/ResumeDelivery itself does not drop mail: queued messages stay in the in-memory queue and drain on resume, and their log writes are buffered and replayed, not lost.

EmailAddressValidator.cs is the single "is this a usable address" check for the UI; EmailSeedService.cs is the idempotent, self-trapping seeder for out-of-the-box defaults; BatchCompletionEmailService.cs composes the completion mail.

Ring/Services/Notifications/ — ToastService.cs (app-wide non-blocking toasts; singleton because a single ToastHost overlay is hosted once), ToastItem.cs, ToastSeverity.cs, ToastBrushPalette.cs (severity → semantic design-system accent brush).

7.8 Predictive — Ring/Services/Predictive/#

All five are pure or read-only.

Related top-level services in the same spirit: GoldenBatchDeviationCalculator.cs (temperature only — not viscosity, and the file says so), IngredientStockForecastService.cs (pure stock-runway math), MaintenanceDueCalculator.cs / MaintenanceReminderEvaluator.cs (which return Unknown with a null percent and an em-dash rather than inventing a number when there is no usable interval), ScaleCalibrationOverdueEvaluator.cs, TankCipDueCalculator.cs, ReceivingVarianceMath.cs (whose honesty rule is that with no configured tolerance an event is never flagged short).

7.9 Roster and group setup#

Ring/Services/Roster/ — TankRoster.cs (the ordered site-configurable slot list, Default() and IndianaPreset()), TankRosterSlot.cs, TankRole.cs, TankRosterState.cs (the process-wide holder over %LocalAppData%\Ring\tank_roster.json, with Changed, RestartRequired, LoadFailed and CaptureSessionBaseline), StorageTankScope.cs (the storage tank numbers an analytics surface must cover, taken from the roster).

Everything downstream of the roster is safety-relevant: see chapter 01 §1.2 and chapter 04 §4.3.

Ring/Services/GroupSetup/ — GroupHardwareSetupState.cs, the legacy Setup → Groups hardware options (tank count, display style, screen tank mapping, cooling/discharge) over %LocalAppData%\Ring\group_hardware_setup.json.

7.10 Operators, configuration, documentation, export#

Authentication proper lives outside Services/, in Ring/Infrastructure/Security/ — AdminCredentialGate.cs, CredentialRotationService.cs (which writes appsettings.local.json), LoginAttemptTracker.cs.

Two more small, easily-missed files sit beside the settings writers in Ring/Infrastructure/Configuration/, not in Security/: SmtpPasswordProtector.cs (DPAPI-protects the SMTP password stored in configuration) and WebhookUrlValidator.cs (the SSRF guard consulted by WebhookAlarmEscalator before it POSTs to an operator-configured URL).

7.11 Top-level services — Ring/Services/*.cs#

Logging, crash and health#

Database lifetime#

DatabaseBackupService.cs, DatabaseHealthService.cs, DatabaseWriterQuiesce.cs, DatabaseMaintenanceLatch.cs — all covered in chapter 05.

Startup and process#

Ambient name state#

MakeReadyTankSupervisorNamesState.cs and StorageTankGroupSupervisorNamesState.cs — in-memory supervisor-entered names (and, for the former, derived inventory line titles), updated on Apply from the matching Setup screen, with a NamesChanged event the UI subscribes to. Both are examples of the ambient-static pattern that is being retired (chapter 02 §2.6).

Formula and recipe#

Maintenance and calibration#

MaintenanceTaskSeeder.cs (seeds sensible defaults on first run), MaintenancePmSeedData.cs (the one replaceable file holding the provisional PM register), MaintenancePlantPmSeedData.cs (the real plant PM register, seeded from the site's own PM forms), MaintenanceDueCalculator.cs, MaintenanceReminderEvaluator.cs, ScaleCalibrationOverdueEvaluator.cs, TankCipDueCalculator.cs.

Analytics and history#

ProcessHistorianService.cs, RuntimeAccumulatorService.cs, TankLevelTrendService.cs, ShiftDryLbsService.cs (one shift's derived dry-lbs total together with the population it was summed over — the pairing is the point), IngredientStockForecastService.cs, GoldenBatchDeviationCalculator.cs, ReceivingVarianceMath.cs, ReceivingVerificationService.cs (manual-first bulk-receiving verification).

Commissioning and legacy#

PlantProfileService.cs (builds a versioned PlantProfile JSON commissioning export), LegacyRs360ImportService.cs (imports legacy tank names, make-ready ingredient names and custom data), DashboardService.cs (coordinates dashboard data from the existing ViewModels — and is on the write-surface register as Infrastructure because it names PlcWriteGuard).

7.12 A note on where not to put things#

Two conventions this catalog makes visible and that are worth preserving:

• Pure math lives in its own type, WPF-free and I/O-free. Almost every calculator above says so in its own doc comment, and the reason is stated in CONTRIBUTING.md: tests prefer WPF-free logic objects over constructing UserControls. A calculation embedded in a code-behind is a calculation with no test.
• "Honesty" types are a pattern here, not an accident. ReportDataUnavailableNotice, RepositoryReadScope, MaintenanceStatus.Unknown, GiveawayCostState.NotConfigured, TankCapability.Unknown, PlcWriteStatus.WrittenUnverified, HasAnyData on the snapshots — each exists so a missing input renders as missing, not as a confident zero. Follow the pattern rather than defaulting.

7.13 Where the evidence lives#

Every subsystem above is described mechanically somewhere in this book, but nothing collects "here is the file you open" in one place. This table does.

Note that the two %ProgramData% roots are not the same directory — Ring\logs\ for the application log versus Ringwood\Ring\ for both JSONL journals. This is a naming accident worth knowing before you go looking for one and find the other empty.

A gate-blocked write, as it appears in the log. PlcWriteGuard.LogBlocked (PlcWriteGuard.cs:97) emits one line per suppressed write:

[WARN] [ReadOnly] PlcTagWriter.Write: PLC write to 'Tanks[3].Preset_Temp'=75 SUPPRESSED (ReadOnlyMode ON — nothing sent to the controller).
[WARN] [ReadOnly] TVCControlPlcService.SetAgitatorModeAsync: PLC write to 'Tanks[2].Agitator_mode'=Auto SUPPRESSED (ReadOnlyMode ON — nothing sent to the controller).

The source half of the message (PlcTagWriter.Write, TVCControlPlcService.SetAgitatorModeAsync) is whatever string the caller passed — it names the method, not a fixed vocabulary, so grepping for SUPPRESSED is more reliable than grepping for one source name.

A healthy boot, roughly in order. Reconstructed from the call order in App.xaml.cs → ConfigurationService.cs → DatabaseInitializer.cs → DatabaseHealthService.cs → MainWindow.xaml.cs; treat this as high-confidence, not an exhaustively traced guarantee — a real boot has more conditional branches than this list:

1. "Configuration loaded successfully from: {path}" (ConfigurationService.cs)
2. "[DatabaseInitializer] Boot sample: Path={path}, FileExistedAtBoot={bool}"
3. "[DatabaseInitializer] Starting. Path={path}, FileExistedAtStartup={bool}"
4. "Database initialized (first run) at {path}" or "Database OK at {path}"
5. "[DatabaseHealthService] PRAGMA integrity_check = ok ({path})"
6. "[DatabaseHealthService] Schema check OK ({path})"
7. "[DatabaseHealthService] Online backup OK → {backupPath} ({bytes} bytes)"
8. Background services (TankNamePlcNameHydrator, PcWriteInteger30StrandedBitMonitor, ReportSchedulerService, ProcessHistorianService, RuntimeAccumulatorService) are silent on success — they only log on failure, so their absence from the log is itself the healthy signal.
9. MainWindow's background reachability probe: "[PlcMonitoring] TryStartPlcMonitoringIfReachable: resolved PLC IP = {ip}", then "[PlcMonitoring] PLC reachable at {ip}:44818 on attempt {n}/3 — starting monitoring.", then the StartPlcMonitoring sequence ending in "[PlcMonitoring] StartPlcMonitoring: started OK (background poll 500ms, UI 1000ms)." (Demo mode replaces the probe with "[PlcMonitoring] Demo mode enabled — skipping TCP reachability probe, starting synthetic pollers directly.")

A caution the log itself creates. At the shipped Debug log level the application log has been observed to grow at roughly 32 MB/h; with the 10 MB × 5 rotation ring that is only about 1.6 hours of retained history (docs/production-readiness/WRITE_ENABLE_READINESS_2026-07-26.md:441-444, which recommends shipping Information for production or enlarging the ring). If you are trying to find what happened more than two hours ago on a Debug-level station, the log may simply no longer have it.

Next: 08 — Testing and Quality.

Verified against#

Every claim in this chapter was read out of these files on 2026-09-01:

Every .cs file under Ring/Services/ and its fifteen subdirectories (Alarms, Audit, Batch, Configuration, Display, Documentation, Email, Export, GroupSetup, Notifications, Operators, PLC, Predictive, Reports, Roster) — summaries taken from each type's own doc comment · Ring/Infrastructure/Security/ (listing) · Ring/Infrastructure/Configuration/AlarmEscalationConfigWriter.cs, AnalyticsSettingsConfigWriter.cs, CostSettingsConfigWriter.cs, AppSettingsSectionWriter.cs, SmtpPasswordProtector.cs, WebhookUrlValidator.cs · Ring/Infrastructure/DependencyInjection/ServiceCollectionExtensions.cs · Ring/Services/PLC/PlcWriteGuard.cs, PlcCommunicationLogService.cs, PlcCommEventLogService.cs, PlcCommEventType.cs · Ring/Services/Email/EmailDeliveryService.cs (RecoverPendingFromPriorRun, RecoveredAfterRestartError, SuspendDelivery/ResumeDelivery, CompletePendingSafe) · Ring/Database/Interfaces/IEmailLogRepository.cs, Ring/Database/Repositories/EmailLogRepository.cs · Ring/Database/Repositories/PlcCommunicationLogRepository.cs · Ring/Services/PLC/UdtTankReader.cs · scripts/Invoke-ProductionGate.ps1 · docs/production-readiness/WRITE_ENABLE_READINESS_2026-07-26.md · CONTRIBUTING.md