Civic / Privacy / Digital Rights

05-ai-publication-sre-observability-and-operator-operations.md

Report summary

This research report establishes a comprehensive Site Reliability Engineering (SRE) and observability architecture for InternationalIntelligence.org, an independent AI-supported publisher operating the Daily Brief and Revolution Watch channels. The operational context indicates a severe failure wher

Status
Research archive item
Category
Civic / Privacy / Digital Rights
Length
6,620 words
Reading time
31 minutes
Report type
evaluation

Key topics

  • Civic / Privacy / Digital Rights
  • Civic
  • Privacy
  • Digital Rights
  • AI
  • SEO
  • SQL
  • Python
  • Runtime

Research provenance

Archive status
Research archive item
Content identity
sha256:318cd7686fa866d2015162ff02da5de051f95faf8f01aaf451013ea12387d2c9

For citation, use the report title and canonical URL. Archival presence does not establish authorship or promote report statements into portfolio evidence.

This page renders the archived Markdown as safe, formatted HTML. It is background research and does not become a portfolio claim without evidence review.

Full report

On this page

Executive Summary

This research report establishes a comprehensive Site Reliability Engineering (SRE) and observability architecture for InternationalIntelligence.org, an independent AI-supported publisher operating the Daily Brief and Revolution Watch channels. The operational context indicates a severe failure wherein a background provider response stalled indefinitely in a zombie state—accepted, queued, but never polled or consumed—while the public-facing and operator interfaces displayed a falsely optimistic "in progress" state. This failure exposes a systemic flaw in how the platform measures time, state, and liveness. A status check does not automatically equal a meaningful publication transition. A page refresh does not constitute computational work. The architecture outlined in this report fundamentally shifts the platform from a fragile, state-based database representation to a robust, event-driven telemetry model. By leveraging OpenTelemetry (OTel) Generative AI Semantic Conventions and rigorous WCAG 2.2 accessibility standards, the framework guarantees that silent stalls, lost wakeups, duplicate generation, and false progress are deterministically caught, immediately surfaced, and safely resolvable without requiring a 24-hour network operations center. The exact UTC research cutoff for this report is Thursday, July 30, 2026 at 9:37:39 PM CDT.

Operational Principles

The publication pipeline is governed by strict operational principles tailored for a small-to-medium independent publisher. The system cannot rely on constant human monitoring, requiring the architecture to inherently distrust assumed states and aggressively validate liveness. Liveness is treated as entirely independent of state. A database record showing a status of "queued" holds no operational value without an accompanying timestamp indicating the last active liveness check. A state without a verifiable heartbeat is defined as a stalled state. Consequently, work requires verification, not assumption. Metrics such as poll counts and progress indicators must only increment when a verified, outward-bound network request is executed and an HTTP response is logged1. Privacy by design is a non-negotiable architectural pillar. In accordance with NIST SP 800-122 guidelines regarding the sanitization of logs and telemetry2, all observability pipelines must aggressively scrub sensitive information before storage or export. Furthermore, the system must not implement behavioral analytics on readers, maintaining a strict firewall between publication operations and audience surveillance. Accessibility operates as a direct component of reliability. If an operator cannot perceive a critical alert due to poor interface design, the alert effectively does not exist. The operator console must strictly adhere to WCAG 2.2 AA standards, ensuring focus management, status message announcements, and appropriate target sizes4. Finally, idempotency takes precedence over all other logic. Recovery actions, whether automated by cron or triggered by bounded operator intervention, must be structurally incapable of creating duplicate publications or wasting provider API budgets.

Observability Data Model and Event Taxonomy

The observability model relies on a strict separation of concerns between logs, metrics, and distributed traces, directly aligned with the OpenTelemetry (OTel) Semantic Conventions for Generative AI7. The pipeline avoids treating "in progress" as an undifferentiated monolith by segregating telemetry into states, events, and metrics. A state represents the calculated, point-in-time condition of a publication stage. It is derived purely from the latest timestamped event evaluated against the current system time. State is never blindly trusted if the time delta between the current time and the last event exceeds the expected Service Level Agreement (SLA). An event is an immutable, timestamped record of an action that successfully occurred, whereas a metric is an aggregated numerical value over a specific time window utilized for triggering Service Level Objective (SLO) alerts. All telemetry emitted by the pipeline follows standardized namespaces to ensure cross-platform compatibility and precise debugging.

Event DomainStandardized OTel Event NameOperational Definition
Schedulercron.heartbeat.emittedA bounded cron execution was triggered to check for due work.
Jobpipeline.job.createdLocal representation of a publication target is saved to storage.
Providergen\_ai.provider.acceptedThe external AI provider accepted the payload and returned an ID.
Providergen\_ai.provider.polledAn actual HTTP GET request was made to the provider status endpoint.
Providergen\_ai.provider.transitionedThe provider status shifted (e.g., from queued to in\_progress).
Pipelinepipeline.output.retrievedThe completed provider payload was downloaded to local memory.
Pipelinepipeline.evidence.boundRetained candidates are explicitly linked to verifiable source citations.
Pipelinepipeline.composition.validatedThe bilingual output passes all semantic parity and policy checks.
Pipelinepipeline.edition.publishedThe HTML, API, and RSS feeds are successfully updated and indexed.

Meaningful-Progress Rules

A core mandate of this architecture is distinguishing meaningful progress from passive observation. The catastrophic failure resulting in a zombie job occurred because the system conflated the passage of time with the execution of work. Meaningful progress represents an irreversible forward movement in the eight-phase publication pipeline. At each stage, progress is explicitly defined. In the "Prepare" phase, progress occurs when target parameters are defined, the job is locked, and a deduplication ID is established. The "Queue research" phase progresses only when the network payload is successfully handed off to the provider. The "Research sources" phase constitutes progress when the provider transitions between discrete states (e.g., queued to in\_progress to completed)9. The "Bind provider evidence" phase advances when the output is successfully retrieved and parsed locally. The "Qualify retained docket" phase requires source URLs to be verified and the candidate deficit mathematically reduced. The "Compose bilingual edition" phase demands that English and Spanish semantic parity is mathematically verified. The "Final checks and save" phase is satisfied when local storage confirms a write without collision. Finally, the "Published" phase is achieved when public indices, APIs, and RSS feeds are demonstrably updated. Certain system interactions are classified as mere observations and must never update the last-meaningful-progress timestamp. If an operator refreshes or views a page, or if a public API is read, no progress has occurred. Furthermore, if a provider status is polled but the returned status string remains unchanged, the system has merely observed stagnation. Attempting to acquire a lock without success, or recalculating a retry time without executing an active network request, similarly fails to constitute progress. The definition of the poll count metric requires strict boundaries. A poll count increments exclusively when the system establishes a TCP connection to the provider, dispatches an HTTP request, and receives a response1. A page refresh by an operator, a local database read, or a cached API response shall never increment the poll count. Furthermore, a real provider poll returning an unchanged queued result serves as liveness evidence—proving the worker is alive and checking—but it is not meaningful progress. Such an event updates the last actual provider poll timestamp but leaves the last meaningful progress timestamp untouched.

Timestamps and Dimensional Counters

To construct a reliable, deterministic timeline capable of exposing silent stalls, the system tracks highly granular timestamps and counters. These metrics form the foundation of all timeout calculations, alert policies, and SLA measurements.

Timestamp Field (ISO 8601 UTC)Operational Definition
ts\_target\_selectedThe precise moment a target date and topic are formally scheduled.
ts\_local\_job\_createdThe moment the local database records the intent to publish.
ts\_provider\_create\_startedThe instant the HTTP POST request is dispatched to the provider.
ts\_provider\_create\_completedThe instant the HTTP POST response is received and parsed.
ts\_provider\_acceptedThe instant a provider response ID is formally persisted locally.
ts\_last\_eligible\_wakeupThe last time a cron or browser fallback was permitted to evaluate the job.
ts\_last\_actual\_provider\_pollThe exact time of the last HTTP GET to the provider status endpoint.
ts\_last\_provider\_status\_changeThe time the provider status string mutated (e.g., in\_progress to completed).
ts\_last\_local\_state\_changeThe last time the local pipeline successfully advanced a discrete stage.
ts\_last\_meaningful\_progressThe anchor timestamp used for calculating timeout and critical stall thresholds.
ts\_output\_retrievedThe time the final text or JSON payload was downloaded from the provider.
ts\_validation\_completedThe time all semantic and evidence checks successfully cleared.
ts\_edition\_savedThe time the structured file was successfully written to the storage system.
ts\_edition\_publishedThe time public-facing endpoints (HTML, API, RSS) were concurrently updated.
ts\_cleanup\_attemptedThe time sensitive temporary data deletion routines were invoked.
ts\_cleanup\_completedThe time sensitive temporary data deletion was cryptographically confirmed.
ts\_next\_retry\_dueThe calculated future timestamp using exponential backoff with jitter11.
ts\_cron\_last\_startedThe last execution launch of the global scheduler heartbeat.
ts\_cron\_last\_completedThe last clean exit of the global scheduler heartbeat.
ts\_operator\_last\_actionThe last time an authenticated operator triggered a state mutation via the console.

The system pairs these timestamps with rigorous counters and dimensions to provide context regarding system load and potential degradation.

Counter / DimensionDefinition
count\_create\_attemptsInteger tracking the number of times a provider POST was attempted.
count\_continuation\_cyclesTotal number of times a stalled job was picked up by a local worker.
count\_actual\_provider\_getsHard integer of verified network status requests made to the provider.
count\_provider\_timeoutsNumber of network or socket timeouts experienced during external egress.
count\_local\_validation\_attemptsNumber of times the internal semantic validator was invoked on a payload.
count\_retained\_candidatesNumber of successful research claims retained post-validation.
count\_rejected\_candidatesNumber of hallucinated or unverified claims explicitly dropped12.
count\_evidence\_bindsNumber of explicit source URLs successfully linked to retained claims.
count\_unresolved\_hintsNumber of research threads that failed to yield verifiable evidence.
count\_corroborated\_candidatesClaims verified independently by at least two distinct source domains.
count\_composition\_attemptsAttempts to format the final bilingual output prior to saving.
dim\_source\_catalog\_sizeInteger representing the total allowable source domains in the configuration.
dim\_wakeup\_sourceSource of liveness execution (e.g., cron, operator, browser\_fallback).
dim\_channelTarget channel identifier (daily\_brief or revolution\_watch).
dim\_model\_routeSpecific LLM or provider endpoint executing the research13.

Timeline Deduplication Rules

Repeated identical observations must be coalesced to avoid log flooding, without masking the duration of a stall. The architecture utilizes OpenTelemetry span structures to manage prolonged wait states gracefully. When an ongoing wait phase begins, an OTel span representing the "waiting for provider" phase is opened. If the ts\_last\_actual\_provider\_poll occurs and the provider returns an unchanged status (e.g., queued), the system does not emit a distinct top-level log line. Instead, it updates a last\_polled\_at high-water mark within the existing span and increments the count\_actual\_provider\_gets counter. The polling events are recorded strictly as OTel span events (e.g., event.name \= poll\_attempt, status \= unchanged). To ensure absolute idempotency, every provider request and database mutation must include a deterministic idempotency key derived from the combination of the channel, target\_date, and stage. If a cron wakeup triggers while a job is already actively polling, the presence of the idempotency key causes the secondary wakeup to abort silently, preventing thundering herd scenarios and duplicate network requests15.

Health-Code and Error-Code Taxonomy

To eliminate the dangerous ambiguity of a singular "in progress" state, the system enforces a strict state taxonomy separated into public-safe indicators and private operational diagnostics. Public-safe health states are designed to remain transparent without leaking internal mechanics, provider names, or prompt contexts. A SCHEDULED state indicates work is planned for a future target date. A WAITING state indicates work is scheduled but currently outside its optimal generation window. When work is securely held in the pipeline backlog, it is QUEUED. During active research or composition, the state is ACTIVE. If an operational delay extends the publication window, the system displays PUBLICATION DELAYED, indicating engineering awareness. Upon completion, the state is PUBLISHED. Scheduled downtime is explicitly marked as MAINTENANCE. Private operator health states require vastly more granularity. Operators must differentiate between a job that is PENDING (newly created, awaiting its first provider handshake) and one that is CONTINUING (alive, healthy, and polling within its exponential backoff window). If the backoff timer elapses, the state becomes POLL DUE. If the ts\_next\_retry\_due is in the past by more than five minutes, the state escalates to POLL OVERDUE, indicating a scheduler failure. Degraded states include PROVIDER SLOW (status unchanged for over two hours), PROVIDER TIMEOUT (network requests failing to establish connections), and LOCAL VALIDATION FAILED (output retrieved but failing semantic parity or evidence checks). If a state becomes deadlocked, it is marked REPAIR NEEDED, requiring manual operator intervention. Systemic failures include SCHEDULER MISSING, CONFIGURATION MISMATCH, STORAGE UNAVAILABLE, and TERMINAL FAILURE (exhaustion of all retries). The error-code taxonomy strictly categorizes failures to dictate automated recovery behaviors.

Error CodeClassificationDescriptionRecoverability
ERR\_PROV\_429Rate LimitProvider rate limits exceeded.Auto-recover via Jitter Backoff11.
ERR\_PROV\_500UpstreamProvider API returned internal server error.Auto-recover via Jitter Backoff.
ERR\_VAL\_EVIDValidationRetained candidates lack sufficient verifiable URLs.Operator intervention required.
ERR\_VAL\_LANGValidationSpanish and English text lack semantic parity.Operator intervention required.
ERR\_SYS\_LOCKConcurrencyPipeline failed to acquire stage lock.Auto-recover on next wakeup.
ERR\_CRON\_DEADInfrastructureHeartbeat missing; cron failed to execute.Infrastructure escalation required.

Data Classification and Redaction Policy

Data exposure is strictly compartmentalized to maintain security, protect proprietary prompts, and preserve reader trust. The matrix below defines data visibility boundaries.

Data ElementPublic Status PagePrivate Operator ConsoleDownloadable Support Bundle
Pipeline Stage (1-8)Masked entirely as "Active"VisibleVisible
Provider Response IDsHiddenHiddenVisible
Prompts & Text PayloadsHiddenHiddenRedacted / Summarized
Source URLs under ReviewHiddenVisibleVisible
Filesystem PathsHiddenHiddenVisible (Root paths sanitized)
Credentials/API KeysHiddenHiddenStrictly Excluded
Internal Network IPsHiddenHiddenStrictly Excluded
Anti-Abuse ThresholdsHiddenHiddenVisible
Health CodeMapped to Public TaxonomyRaw State VisibleRaw State Visible

Following NIST SP 800-122 guidelines2 and OpenTelemetry security best practices16, the system enforces a rigorous redaction policy. All support bundles must pass through an OTel Redaction Processor prior to export. Regex matching is utilized to drop any sequences resembling API keys, internal IP ranges, or OAuth tokens. Full prompt payloads are replaced with mathematical hashes or length counts to allow debugging of truncation and token-limit issues without exposing intellectual property or unpublished intelligence. Log retention is strictly limited to 14 days for debug telemetry, ensuring unnecessary sensitive data is automatically purged.

Alert Policy and Wakeup Observability

Alerting must accurately distinguish between a healthy system with zero scheduled work and a dead scheduler. A cron job is mandated to run every five minutes. If there is no pending work, it must still emit a cron.heartbeat.emitted event with a work\_found=false attribute. If the ts\_cron\_last\_completed timestamp grows older than 15 minutes, an immediate page is escalated to the on-call operator, as the pipeline is effectively dead. To detect the precise failure that prompted this report—where a job was accepted but never polled—the system actively queries for jobs where ts\_provider\_accepted exists, ts\_last\_actual\_provider\_poll is null, and the current time exceeds ts\_next\_retry\_due. This condition triggers a delayed grouped alert after 15 minutes, allowing operators to intervene before the provider response ages out entirely. The alert escalation matrix is designed to prevent alert fatigue. Immediate alerts are reserved for missing cron heartbeats, storage unavailability, and duplicate publication detection. Delayed alerts (triggering after 15 minutes) handle overdue polls and validation rejections. Grouped alerts, evaluated daily, handle cleanup failures and slow provider responses (unless a publication deadline is imminent). Alerts for provider timeouts are automatically suppressed during known, documented vendor outages to prevent unnecessary noise.

Operator Console and Accessibility Architecture

The private operator console must provide unambiguous state transparency and prevent nervous, repetitive clicking without requiring deep technical knowledge from the user. Operators are strictly bounded by workflow rules. They may not choose arbitrary prompts, URLs, models, or dates, which would introduce untracked entropy into the system. Permitted actions are limited to: Run one due continuation, Refresh canonical state, Download a bounded pipeline report, Run full diagnostics, Refresh runtime cache, Suspend a channel, Quarantine a response, and Close authorization. Action labels are strictly standardized: "Start" initiates a new run, "Resume" attempts to clear a validation lock, "Poll" forces a provider liveness check, "Consume" retrieves a completed payload, and "Publish" writes the final files. To prevent nervous clicking, any action button immediately transitions to a disabled role="button" aria-disabled="true" state upon click. The button then displays a visual and auditory countdown timer mapping exactly to the jitter backoff window, communicating clearly that the system is processing and further clicks are mechanically blocked.

Accessibility Requirements (WCAG 2.2 AA)

The interface must adhere to strict accessibility mandates4. Under WCAG 4.1.3 (Status Messages), live pipeline transitions must be injected into an aria-live="polite" container with role="status". Critical failures utilize role="alert". This ensures screen readers announce the update without stealing keyboard focus from the operator. Under WCAG 2.2.1 (Timing Adjustable), auto-refresh mechanisms must feature a prominent pause button, allowing cognitive processing time. Under WCAG 2.4.7 (Focus Visible), high-contrast focus rings must track operator keyboard navigation explicitly throughout the dashboard. Under WCAG 2.5.8 (Target Size), all interactive touch targets must be a minimum of 24x24 CSS pixels with adequate spacing to prevent accidental, catastrophic actions like quarantining a channel. Finally, loading spinners and progress indicators must obey the operating system's prefers-reduced-motion media query, gracefully falling back to a static progress percentage. English and Spanish parity is mandated across all operator terminology to ensure bilingual operational capability. Terms translate directly: Start to Iniciar, Resume to Reanudar, Poll to Consultar, Consume to Procesar, Publish to Publicar, and Quarantine to Poner en cuarentena.

Console Information Architecture (Above the Fold)

The interface employs progressive disclosure. The "above the fold" view provides immediate health context without overwhelming the operator with JSON payloads or raw logs.

================================================================================ INTERNATIONAL INTELLIGENCE - PUBLICATION OPERATIONS CONSOLE

[ CHANNEL: DAILY BRIEF ] | [ STATUS: HEALTHY - ACTIVE ] | [ SYSTEM TIME: 14:02 UTC ]

PIPELINE STAGE: (4/8) BIND PROVIDER EVIDENCE Liveness: \[ OK \] Last Cron Heartbeat: 2 mins ago Provider: \[ OK \] Last Actual Poll: 4 mins ago (Status: in\_progress) Next Wakeup: \[ 01:14 \] (Countdown active...) CANDIDATE DEFICIT METRICS:

  • Retained: 12 | Rejected: 3 | Bound Evidence: 12 | Deficit: 0

AVAILABLE ACTIONS: [ Refresh Canonical State ] [ Download Pipeline Report ] [ Suspend Channel ]

Information regarding source catalogs, detailed diagnostic traces, and full evidence binding matrices are available below the fold, exposed only via deliberate user interaction.

Support Bundle and Diagnostic Contract

When a complex failure exceeds operator capacity, the system allows the generation of a sanitized support bundle. To ensure diagnostic completeness, the system employs a Diagnostic Contract: a partial probe must never be mistaken for a full capability test. The diagnostic payload contains a diagnostic\_completeness boolean array representing: Storage Read, Storage Write, Network Egress, Database Connectivity, and Provider Authentication. If any of these probes fail or time out, the test is permanently marked PARTIAL\_DEGRADATION. The support bundle is generated as a compressed archive containing:

1. pipeline-state.json: A redacted database dump of the current job, stripped of all internal IDs.

2. telemetry-events.csv: The last 1,000 span events, processed through the OTel redaction pipeline.

3. cron-heartbeats.log: The trailing 24 hours of scheduler health metrics.

4. diagnostic-results.json: The explicit result of the capability probe.

Correlation IDs map local jobs to provider calls and timelines. A primary trace\_id spans the entire 8-stage pipeline from target creation to publication cleanup, allowing seamless distributed tracing across all discrete events.

SLI, SLO, and Error Budget Framework

A daily intelligence publication requires stringent, measurable Service Level Objectives (SLOs) focused on timeliness, accuracy, and platform stability. The Error Budget dictates operational velocity; if the budget is exhausted, feature development must pause to prioritize reliability repairs.

SLO ObjectiveSLI NumeratorSLI DenominatorMeasurement WindowTargetAlert ThresholdOperator / User Consequence
Edition Publication TimelinessEditions successfully published before 06:00 UTCTotal editions scheduled30 Days99.0%\< 99.5%Readers miss morning briefing.
Time to First Provider PollJobs with ts\_provider\_create\_started \- ts\_local\_job\_created \< 2mTotal jobs created7 Days99.9%\< 99.9%Backlog buildup; slow starts.
Max Overdue ContinuationPolling cycles where ts\_actual\_poll \- ts\_next\_retry\_due \< 5mTotal polling cycles7 Days99.0%\< 95.0%Cron failure; jobs stall silently.
Provider Completion LatencyResponses consumed within 10m of provider completed stateTotal completed responses30 Days99.5%\< 98.0%Wasted provider spend; stale news.
Local Validation LatencySemantic and evidence validations completing \< 5mTotal validation attempts7 Days99.0%\< 95.0%Operator UI hangs during saving.
Publication Write LatencyFilesystem and database writes completing \< 10sTotal publication writes30 Days99.9%\< 99.0%Reader encounters 404 on release.
Status FreshnessOperator UI status polling lag \< 30sTotal active operator sessions24 Hours99.9%\< 99.0%Operator acts on stale, unsafe data.
Cron Heartbeat FreshnessHeartbeats with time delta \< 5mExpected heartbeats (288/day)24 Hours99.9%Missing \> 2Pipeline effectively dead.
Duplicate GenerationProvider requests yielding unique API output IDsTotal provider requests30 Days99.9%\> 0.1%Wasted budget; rate limits hit.
Duplicate PublicationEditions published exactly once per specific target dateTotal published editions90 Days100%\> 0%Severe reputational and SEO damage.
Stranded Accepted WorkProvider jobs reaching a terminal state (not stuck \> 24h)Total accepted provider jobs30 Days99.9%\< 99.5%Silent zombie jobs consuming DB.
Source Qualification SuccessCandidates passing verifiable evidence binding checksTotal candidates processed30 Days95.0%\< 90.0%Hallucinated news blocks pipeline.
Operator Recovery TimeMean time to successfully resolve a REPAIR NEEDED stateTotal repair incidents30 Days90.0%\> 30mExtended delay for readers.
Cleanup CompletionTemporary JSON/text files successfully deleted post-publishTotal temp files created7 Days99.9%\< 99.0%Storage exhaustion over time.
Diagnostic RedactionSupport bundles successfully passing PII regex validationTotal support bundles generated90 Days100%\> 0%Unacceptable privacy/security breach.

Known provider global outages are automatically excluded from the publication timeliness SLI calculations, though the downtime is deducted from the overall vendor error budget for future contract review.

Incident Runbooks

The following 20 runbooks provide deterministic, safe resolution paths for operators managing the pipeline.

ScenarioSymptoms & Confirmation EvidenceImmediate Containment & Safe ActionsProhibited Actions & Escalation
1\. Queued response with zero pollsJob in Stage 3\. ts\_provider\_accepted populated, count\_actual\_provider\_gets is 0, age \> 15m. Telemetry shows no gen\_ai.provider.polled events.Verify cron heartbeat is alive. Manually click Run one due continuation.Do not restart the server (memory state will drop). Escalate to SRE if manual continuation fails network egress.
2\. In-progress response beyond durationProvider status in\_progress \> 2h. ts\_last\_provider\_status\_change stalled. Polls occurring but unchanging19.Check provider public status for Batch API degradation. Quarantine response and spin up secondary fallback.Do not continuously poll without jitter. No escalation required (expected during vendor degradation).
3\. Completed response not consumedProvider status completed, but stuck in Stage 3\. API confirms completion, but ts\_output\_retrieved is null.Click Consume to force retrieval step. Verify storage permissions if retrieval fails.Do not mark as terminal; data is paid for. Escalate to SRE if storage layer returns 500s.
4\. Cron heartbeat missingts\_cron\_last\_completed \> 15m. No cron.heartbeat.emitted events in logs.Execute bounded browser fallback to maintain daily schedule. Restart cron daemon / scheduler service.Do not script a secondary overlapping cron to "fix" the first. Escalate to Infrastructure team.
5\. Cron runs but does not contact providerHeartbeats present (work\_found=false), but jobs sitting in POLL\_DUE.Click Run one due continuation. Inspect database query logic fetching "due" jobs.Do not bypass state locks. Escalate to Application Engineering to patch job-fetching SQL/ORM logic.
6\. Wrong document root after deploymentPublic site shows 404s after PUBLISHED. ts\_edition\_published updated, HTTP GET fails.Rollback recent deployment or symlink document root. Re-run Stage 8 (Publish) from console.Do not manually edit HTML files in production. Escalate to SRE / DevOps.
7\. Runtime version mismatchCONFIGURATION MISMATCH health state. DB schema version \!= application binary version.Suspend channel to prevent data corruption. Rollback application binary to match database.Do not force database migrations forward during an active run. Escalate to DevOps.
8\. Storage permission failurePipeline stalls at Stage 7\. Logs show EACCES or 403 Forbidden on Disk/S3 writes.Suspend channel. Rectify IAM roles or POSIX permissions on the storage mount. Run diagnostics.Do not chmod 777 production directories. Escalate to SRE.
9\. Provider authentication failureERR\_PROV\_401 or 403 on polling. count\_provider\_timeouts or auth failures spike to 100%.Update API keys in secrets manager. Click Refresh runtime cache to pull new keys into memory.Do not hardcode keys into the database to bypass the secrets manager. Escalate to Security if compromised.
10\. Provider rate limitERR\_PROV\_429. Provider HTTP status 42911.Allow exponential backoff with jitter to naturally handle the transient failure15.Do not click Resume repeatedly (worsens rate limit). Escalate to SRE for quota increase if persistent \> 24h.
11\. Provider server errorERR\_PROV\_500 / 503\. Provider returning 5xx errors.Wait. Let exponential backoff handle the upstream failure. Quarantine response if tied to a malformed payload.Do not change the prompt payload to "debug" the provider. Escalate to vendor support.
12\. Validation rejects all candidatesStage 5 loops endlessly or fails ERR\_VAL\_EVID. count\_rejected\_candidates equals total candidates.Quarantine response (severe hallucinations detected). Start a new generation pipeline.Do not lower validation thresholds to force publication. Escalate to Editorial / Prompt Engineering.
13\. Evidence binder repeatedly abstainsStage 4 fails to match candidates to URLs. count\_evidence\_binds is 0\.Check if external search API is unreachable. Run diagnostics on external search connectivity.Do not manually insert URLs into the database. Escalate to SRE for network egress investigation.
14\. Bilingual composition fails semantic parityStage 6 fails ERR\_VAL\_LANG. English and Spanish outputs do not align logically.Quarantine response. Re-trigger Stage 6 composition with a strictly bounded parameter set (lower temperature).Do not manually edit the Spanish output to match; breaks reproducibility. Escalate to AI Engineering.
15\. Edition saved but not indexedts\_edition\_saved populated, ts\_edition\_published is null. APIs return old data.Check indexing service health. Manually click Publish to retry index population.Do not delete the saved edition from the database. Escalate to Application Engineering.
16\. RSS/API updated without HTML editionRSS feed shows new edition, website returns 404\. Publish attempt metrics mismatched.Temporarily revert RSS feed to previous state. Check HTML template rendering logs for syntax errors.Do not leave the broken link live. Escalate to Frontend Engineering to fix template crash.
17\. Duplicate provider responsesCost spikes; dim\_target\_date has two distinct ts\_provider\_create\_completed events.Suspend channel to halt duplication. Delete the secondary rogue pipeline job from the database.Do not delete the locked/primary job. Escalate to SRE to enforce database uniqueness constraints.
18\. Operator session suspected compromisedAnomalous manual actions (Refresh, Consume) outside normal hours.Click Close authorization to invalidate all active operator sessions. Audit recent mutations.Do not ignore the anomaly. Escalate to Security team for MFA review and credential rotation.
19\. Cleanup failurets\_cleanup\_attempted exists, ts\_cleanup\_completed is null. Temp files remaining on disk.Trigger a manual batch cleanup script from the console.Do not recursively force delete without verifying the path target. Escalate to DevOps if disk reaches 85%.
20\. Daily Brief and Revolution Watch both overduets\_next\_retry\_due overdue for all channels. Both channels miss publication SLOs simultaneously.Verify core database and network egress. Run full diagnostics to isolate systemic failure layer.Do not restart the entire infrastructure blindly. Escalate to full SRE and Engineering team via page.

Recurring Operational Reviews

To ensure continuous improvement, the SRE team must execute structured operational reviews. Daily reviews focus on analyzing the previous 24 hours of SLO adherence and investigating any delayed alerts. Weekly reviews examine candidate deficit metrics, tracking the ratio of retained versus rejected hallucinations12 to determine if prompt engineering adjustments are required. Monthly reviews analyze the error budget depletion, evaluating provider uptime and API expenditure. Release reviews occur 24 hours post-deployment, specifically validating that the OTel telemetry event taxonomy remains intact and WCAG 2.2 accessibility scanners report zero regressions on the operator console.

Postmortem Template and Chaos Plan

Every incident that meaningfully depletes the Error Budget must generate a blameless postmortem document. The template strictly requires: Incident Title and Date, Authors and Reviewers, Impact (quantifying how readers and the publication schedule were affected), Timeline (exact UTC timestamps of detection, escalation, and resolution utilizing observability data), Root Cause analysis, and Action Items (concrete, ticketed tasks to prevent recurrence, such as adjusting jitter backoff calculations). To ensure organizational readiness, the SRE team conducts monthly failure drills (Game Days). A Network Blackhole drill blocks all egress traffic to the AI provider to verify the system transitions gracefully to PROVIDER TIMEOUT and respects exponential backoff without crashing11. A Disk Full drill mounts a 100% full dummy volume to verify that STORAGE UNAVAILABLE triggers an immediate page without data corruption. A Cron Death drill kills the scheduler process to verify the 15-minute SCHEDULER MISSING grouped alert fires reliably. Finally, a Hallucination Injection drill mocks the provider to return 100% unverifiable claims, verifying that Stage 5 rejects all candidates and transitions safely to LOCAL VALIDATION FAILED.

Release-Observability Checklist & Operational Acceptance Tests

Before any new pipeline code is merged to production, it must pass the Release-Observability Checklist: Telemetry events map perfectly to the correct OTel GenAI SemConv namespace; UI changes pass automated Axe/WCAG 2.2 accessibility scanners; new pipeline states map securely to Health and Error Codes; and runbooks are updated for any introduced dependencies. The architecture mandates the continuous execution of 60 Operational Acceptance Tests (OATs) to guarantee systemic reliability.

CategoryOAT Requirements
Cron & Wakeup1\. Cron heartbeat emits exactly every 5m. 2\. Cron exits gracefully if no work found. 3\. Browser fallback emits identical telemetry. 4\. Overlapping crons abort via concurrency locks. 5\. Missing heartbeat triggers delayed alert. 6\. Job in POLL\_DUE is picked up. 7\. Job with future retry is ignored. 8\. Wakeup source tagged in telemetry. 9\. Cron logs include release version. 10\. System recovers immediately post-restart.
Provider & Network11\. POST populates ts\_provider\_create\_started. 12\. Success updates ts\_provider\_accepted. 13\. count\_create\_attempts increments strictly on egress. 14\. count\_actual\_provider\_gets increments on GETs. 15\. Unchanged queued updates ts\_last\_actual\_provider\_poll only. 16\. Transition updates ts\_last\_provider\_status\_change. 17\. 429 triggers backoff. 18\. Backoff includes 20% random jitter11. 19\. 500 error prevents worker crash. 20\. Network timeout flags PROVIDER TIMEOUT.
State & Validation21\. Stage 3 to 4 updates ts\_last\_local\_state\_change. 22\. Retrieval failure leaves job in Stage 3\. 23\. Success populates ts\_output\_retrieved. 24\. Semantic failure flags ERR\_VAL\_LANG. 25\. Evidence failure increments count\_rejected\_candidates. 26\. Source validation maps exactly one URL per candidate. 27\. Stage 7 requires DB lock before file write. 28\. Duplicates blocked by DB constraint. 29\. PUBLISHED confirms HTML/RSS writes. 30\. Quarantine halts all state transitions.
Telemetry31\. gen\_ai.usage.input\_tokens recorded22. 32\. Idempotency keys appended to spans. 33\. Span duration remains open during polling. 34\. Unchanged polls coalesce under single span. 35\. ts\_last\_meaningful\_progress untouched during passive polls. 36\. Alerts fire when progress \> 4h. 37\. Operator actions log ts\_operator\_last\_action. 38\. Metrics exportable via OTLP. 39\. Health codes map accurately. 40\. Error budgets exclude maintenance.
Privacy & Cleanup41\. PII regex strips API keys16. 42\. Prompt payloads hashed in telemetry. 43\. Support bundle executes without exposing credentials. 44\. Cleanup job triggers immediately post-publish. 45\. ts\_cleanup\_completed populated on success. 46\. Cleanup failure triggers grouped alert. 47\. SSO token expires post configuration limit. 48\. Close authorization invalidates cookies. 49\. Arbitrary prompt injection rejected by backend. 50\. Cross-tenant data leakage prevented.
UI & Accessibility51\. 100% keyboard navigability. 52\. Pipeline changes inject text into aria-live5. 53\. Error notifications trigger role="alert"23. 54\. Action buttons have min 24x24px target size6. 55\. Clicks transition to aria-disabled="true". 56\. Timers respect prefers-reduced-motion. 57\. English/Spanish exact parity. 58\. High-contrast focus visible present6. 59\. Auto-refresh pausable via keyboard. 60\. Color not used as sole health indicator.

Machine-Readable Appendices

The following appendices provide the exact schema definitions necessary for implementing the observability and diagnostic contracts.

Appendix A: publication-event-taxonomy.json

JSON { "namespaces": \["gen\_ai", "pipeline"\], "events": \[ { "name": "gen\_ai.provider.polled", "attributes": { "gen\_ai.operation.name": "string", "gen\_ai.provider.name": "string", "pipeline.channel": "string", "pipeline.idempotency\_key": "string" } }, { "name": "pipeline.output.retrieved", "attributes": { "gen\_ai.usage.input\_tokens": "integer", "gen\_ai.usage.output\_tokens": "integer", "pipeline.target\_date": "string" } } \] }

Appendix B: health-code-register.json

JSON { "health\_codes": \[ {"internal\_state": "WAITING", "public\_safe": true, "description": "Scheduled outside optimal window."}, {"internal\_state": "ACTIVE", "public\_safe": true, "description": "Actively researching/composing."}, {"internal\_state": "POLL\_OVERDUE", "public\_safe": false, "description": "Scheduler failed to execute retry."}, {"internal\_state": "PROVIDER\_SLOW", "public\_safe": false, "description": "Status unchanged \> 2 hours."}, {"internal\_state": "REPAIR\_NEEDED", "public\_safe": false, "description": "Manual unblocking required."} \] }

Appendix C: sli-slo-register.csv

Code snippet SLO\_Objective,SLI\_Numerator,SLI\_Denominator,Window,Target,Alert\_Threshold Publication\_Timeliness,Editions\_Published\_Before\_0600,Total\_Editions\_Scheduled,30d,99.0%,\<99.5% Max\_Overdue\_Continuation,Polls\_With\_Delta\_Under\_5m,Total\_Polling\_Cycles,7d,99.0%,\<95.0% Duplicate\_Publication,Editions\_Published\_Exactly\_Once,Total\_Published\_Editions,90d,100%,\>0% Source\_Qualification\_Success,Candidates\_Passing\_Evidence,Total\_Candidates\_Processed,30d,95.0%,\<90.0% Diagnostic\_Redaction,Bundles\_Passing\_PII\_Regex,Total\_Bundles\_Generated,90d,100%,\>0%

Appendix D: support-bundle-field-policy.csv

Code snippet Data\_Field,Redaction\_Policy,Regex\_Pattern,Action api\_key,Strict\_Scrub,sk-\[a-zA-Z0-9\]{32,},REPLACE\_WITH\_\[REDACTED\] prompt\_payload,Hash\_Content,.\*,REPLACE\_WITH\_SHA256\_AND\_LENGTH internal\_ip,Strict\_Scrub,^(10\\.|192\\.168\\.|172\\.(1\[6-9\]|2\[0-9\]|3\[0-1\])\\.),REPLACE\_WITH\_\[INTERNAL\_IP\]

Appendix E: incident-runbook-index.json

JSON { "runbook\_mapping": \[ {"health\_code": "PROVIDER\_TIMEOUT", "runbook\_id": 11, "title": "Provider server error"}, {"health\_code": "LOCAL\_VALIDATION\_FAILED", "runbook\_id": 12, "title": "Validation rejects all candidates"}, {"health\_code": "SCHEDULER\_MISSING", "runbook\_id": 4, "title": "Cron heartbeat missing"} \] }

Appendix F: Source Register

JSON { "sources": \[ {"id": "22", "title": "EqualWeb: WCAG 2.2 \- 4.1.3 Status Messages"}, {"id": "24", "title": "Calling All Minds: WCAG 4.1.3 Resource Guide"}, {"id": "26", "title": "Calling All Minds: WCAG ARIA live regions best practices"}, {"id": "48", "title": "Greptime: OpenTelemetry GenAI Semantic Conventions"}, {"id": "52", "title": "Clickhouse: OpenTelemetry Semantic Conventions definitions"}, {"id": "54", "title": "OpenTelemetry GitHub: gen\_ai\_attributes.py"}, {"id": "58", "title": "OpenTelemetry Specs: gen\_ai.\* attribute registry"}, {"id": "66", "title": "NIST SP 800-122: Guide to Protecting PII Confidentiality"}, {"id": "68", "title": "NIST ITS Cybersecurity Controls (SP 800-122 reference)"}, {"id": "74", "title": "OpenTelemetry Docs: Handling Sensitive Data and Redaction"}, {"id": "80", "title": "Dynatrace: OTel Collector Redaction Config Use Cases"}, {"id": "85", "title": "AWS Architecture: Throttling and Exponential Backoff with Jitter"}, {"id": "89", "title": "Singhajit: Jitter and Thundering Herd mitigation"}, {"id": "94", "title": "W3C: WCAG 2.2 Guideline 2.2.1 Timing Adjustable"}, {"id": "97", "title": "Arizona Accessibility: WCAG 2.2 AA Highlights and 2.5.8 Target Size"}, {"id": "108", "title": "Vercel AI SDK Core Telemetry: Input/Output Tokens"}, {"id": "109", "title": "Rewire.it: Kosmos AI Research Session and Verification"}, {"id": "112", "title": "arXiv: Phantom References and Hallucinated Citations"}, {"id": "125", "title": "OpenAI Community Forum: Batch API stuck in in\_progress over 24h"}, {"id": "131", "title": "Sinaptia: OpenAI Batch API \- Handling expired and failed states"}, {"id": "132", "title": "OpenAI Community Forum: API stalling issues"}, {"id": "137", "title": "Tella App Accessibility Audit: 2.4.7 Focus Visible"} \] }

\\pagebreak

Five-Minute Operator Triage Card

PURPOSE: Utilize this card to rapidly diagnose a stalled publication pipeline without requiring deep engineering access or database queries. Check these five metrics within the Operator Console to determine the exact failure domain.

1. Is the Scheduler Alive? (Missing Wakeup)

  • Look at: ts\_cron\_last\_completed
  • Condition: Is the timestamp older than 15 minutes?
  • Diagnosis: YES \-\> The cron scheduler is dead. The system has mechanically stopped waking up to check for due work.
  • Action: Trigger a manual Refresh Canonical State or execute a bounded browser fallback to force a localized wakeup. Escalate to Infrastructure immediately (Runbook 4).

2. Is there actual work to do? (Waiting)

  • Look at: Pipeline Stage and ts\_next\_retry\_due
  • Condition: Is the stage set to WAITING and the next retry time in the future?
  • Diagnosis: YES \-\> The system is perfectly healthy. It is obeying a calculated backoff or scheduled delay.
  • Action: Do nothing. Wait for the countdown timer to expire.

3. Is the provider unreachable? (Terminal/Network Failure)

  • Look at: count\_provider\_timeouts and Health State
  • Condition: Are network timeouts spiking, or is the state officially PROVIDER TIMEOUT?
  • Diagnosis: YES \-\> The external AI provider is down, or local network egress is blocked by a firewall or routing issue.
  • Action: Run the full diagnostics probe to verify outbound connectivity. Check the external provider's public status page. Wait for exponential backoff to handle recovery (Runbook 11).

4. Is the provider working, but extremely slow? (Slow Provider Work)

  • Look at: ts\_last\_actual\_provider\_poll vs ts\_last\_provider\_status\_change
  • Condition: Is the poll timestamp recent (\< 5m), but the status change timestamp is old (\> 1h), and the status string remains in\_progress or queued?
  • Diagnosis: YES \-\> The pipeline is perfectly healthy and actively polling. The AI provider is heavily congested and taking unusually long to process the background batch.
  • Action: Do nothing initially. If it exceeds acceptable SLAs and threatens publication timeliness, click Quarantine response and spin up a fallback generation (Runbook 2).

5. Did the provider finish, but we rejected it? (Local Validation Failure)

  • Look at: count\_rejected\_candidates vs count\_retained\_candidates
  • Condition: Are rejected candidates extremely high, with zero retained? Is the Health State LOCAL VALIDATION FAILED?
  • Diagnosis: YES \-\> The pipeline successfully completed generation and retrieved the data, but the AI hallucinated or failed to cite verifiable sources. Internal security and semantic guards successfully blocked publication.
  • Action: Click Quarantine response to dump the bad payload. Start a fresh, localized run with bounded parameters (Runbook 12).

Works cited

1. The untold challenges of OpenAI's batch processing API \- SINAPTIA, https://sinaptia.dev/posts/the-untold-challenges-of-openai-s-batch-processing-api/

2. Federal Zero Trust Data Security Guide, https://resources.data.gov/assets/documents/Zero-Trust-DataSecurityGuide\_RevisedMay2025\_CIO.govVersion.pdf

3. Intelligent Transportation Systems (ITS) Security Control Set for Closed-Circuit Television \- ROSA P, https://rosap.ntl.bts.gov/view/dot/91213/dot\_91213\_DS1.pdf

4. WCAG Status Messages Explained, https://www.getstark.co/wcag-explained/robust/compatible/status-messages/

5. 4.1.3 Status Messages — EqualWeb Academy, https://www.equalweb.com/academy/standards/criterion-4-1-3.html

6. Web Content Accessibility Guidelines (WCAG) 2.2 Audit \- Tella app Android, https://tella-app.org/assets/files/2023.11%20-%20Tella%20Android%20accessibility%20audit.docx-437f28cafa97274fb4bc13285e81329d.pdf

7. How OpenTelemetry Traces LLM Calls, Agent Reasoning, and MCP Tools | Greptime, https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions

8. OpenTelemetry semantic conventions explained | Engineering | ClickHouse Resource Hub, https://clickhouse.com/resources/engineering/opentelemetry-semantic-conventions

9. Video generation with Sora | OpenAI API, https://developers.openai.com/api/docs/guides/video-generation

10. Assistants API deep dive \- OpenAI Developers, https://developers.openai.com/api/docs/assistants/deep-dive

11. Optimize your applications for scale and reliability on Amazon Bedrock | Artificial Intelligence, https://aws.amazon.com/blogs/machine-learning/optimize-your-applications-for-scale-and-reliability-on-amazon-bedrock/

12. Kosmos: What a 12-Hour AI Research Session Actually Produces \- rewire.it, https://rewire.it/blog/kosmos-12-hour-ai-research-session/

13. opentelemetry-python/opentelemetry-semantic-conventions/src/opentelemetry/semconv/\_incubating/attributes/gen\_ai\_attributes.py at main · open-telemetry/opentelemetry-python \- GitHub, https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-semantic-conventions/src/opentelemetry/semconv/\_incubating/attributes/gen\_ai\_attributes.py

14. Gen AI | OpenTelemetry, https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/

15. How to Solve the Thundering Herd Problem in Distributed Systems \- Ajit Singh, https://singhajit.com/thundering-herd-problem/

16. Handling sensitive data \- OpenTelemetry, https://opentelemetry.io/docs/security/handling-sensitive-data/

17. Mask sensitive data with the OTel Collector \- Dynatrace Documentation, https://docs.dynatrace.com/docs/ingest-from/opentelemetry/collector/use-cases/redact

18. How to Meet WCAG (Quick Reference) \- W3C, https://www.w3.org/WAI/WCAG22/quickref/

19. OpenAI batch API gets stuck for hours with status \in\_progress\ \- \#11 by platypus, https://community.openai.com/t/openai-batch-api-gets-stuck-for-hours-with-status-in-progress/931785/11

20. OpenAI batch API gets stuck for hours with status \in\_progress\, https://community.openai.com/t/openai-batch-api-gets-stuck-for-hours-with-status-in-progress/931785

21. Phantom References: Hallucinated Citations That Survive Peer Review at Top‑Tier Conferences \- arXiv, https://arxiv.org/html/2607.00738v1

22. AI SDK Core: Telemetry, https://ai-sdk.dev/v5/docs/ai-sdk-core/telemetry

23. 4.1.3 Status Messages \- WCAG 2.2 \- Calling All Minds, https://callingallminds.com/resources/wcag/4.1.3-status-messages

24. WCAG 2.2 AA Highlights \- Accessibility \- The University of Arizona, https://accessibility.arizona.edu/policies-governance/wcag-22-highlights