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
Key topics
- Civic / Privacy / Digital Rights
- Civic
- Privacy
- Digital Rights
- AI
- SEO
- SQL
- Python
- Runtime
Research provenance
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 Domain | Standardized OTel Event Name | Operational Definition |
|---|---|---|
| Scheduler | cron.heartbeat.emitted | A bounded cron execution was triggered to check for due work. |
| Job | pipeline.job.created | Local representation of a publication target is saved to storage. |
| Provider | gen\_ai.provider.accepted | The external AI provider accepted the payload and returned an ID. |
| Provider | gen\_ai.provider.polled | An actual HTTP GET request was made to the provider status endpoint. |
| Provider | gen\_ai.provider.transitioned | The provider status shifted (e.g., from queued to in\_progress). |
| Pipeline | pipeline.output.retrieved | The completed provider payload was downloaded to local memory. |
| Pipeline | pipeline.evidence.bound | Retained candidates are explicitly linked to verifiable source citations. |
| Pipeline | pipeline.composition.validated | The bilingual output passes all semantic parity and policy checks. |
| Pipeline | pipeline.edition.published | The 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\_selected | The precise moment a target date and topic are formally scheduled. |
| ts\_local\_job\_created | The moment the local database records the intent to publish. |
| ts\_provider\_create\_started | The instant the HTTP POST request is dispatched to the provider. |
| ts\_provider\_create\_completed | The instant the HTTP POST response is received and parsed. |
| ts\_provider\_accepted | The instant a provider response ID is formally persisted locally. |
| ts\_last\_eligible\_wakeup | The last time a cron or browser fallback was permitted to evaluate the job. |
| ts\_last\_actual\_provider\_poll | The exact time of the last HTTP GET to the provider status endpoint. |
| ts\_last\_provider\_status\_change | The time the provider status string mutated (e.g., in\_progress to completed). |
| ts\_last\_local\_state\_change | The last time the local pipeline successfully advanced a discrete stage. |
| ts\_last\_meaningful\_progress | The anchor timestamp used for calculating timeout and critical stall thresholds. |
| ts\_output\_retrieved | The time the final text or JSON payload was downloaded from the provider. |
| ts\_validation\_completed | The time all semantic and evidence checks successfully cleared. |
| ts\_edition\_saved | The time the structured file was successfully written to the storage system. |
| ts\_edition\_published | The time public-facing endpoints (HTML, API, RSS) were concurrently updated. |
| ts\_cleanup\_attempted | The time sensitive temporary data deletion routines were invoked. |
| ts\_cleanup\_completed | The time sensitive temporary data deletion was cryptographically confirmed. |
| ts\_next\_retry\_due | The calculated future timestamp using exponential backoff with jitter11. |
| ts\_cron\_last\_started | The last execution launch of the global scheduler heartbeat. |
| ts\_cron\_last\_completed | The last clean exit of the global scheduler heartbeat. |
| ts\_operator\_last\_action | The 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 / Dimension | Definition |
|---|---|
| count\_create\_attempts | Integer tracking the number of times a provider POST was attempted. |
| count\_continuation\_cycles | Total number of times a stalled job was picked up by a local worker. |
| count\_actual\_provider\_gets | Hard integer of verified network status requests made to the provider. |
| count\_provider\_timeouts | Number of network or socket timeouts experienced during external egress. |
| count\_local\_validation\_attempts | Number of times the internal semantic validator was invoked on a payload. |
| count\_retained\_candidates | Number of successful research claims retained post-validation. |
| count\_rejected\_candidates | Number of hallucinated or unverified claims explicitly dropped12. |
| count\_evidence\_binds | Number of explicit source URLs successfully linked to retained claims. |
| count\_unresolved\_hints | Number of research threads that failed to yield verifiable evidence. |
| count\_corroborated\_candidates | Claims verified independently by at least two distinct source domains. |
| count\_composition\_attempts | Attempts to format the final bilingual output prior to saving. |
| dim\_source\_catalog\_size | Integer representing the total allowable source domains in the configuration. |
| dim\_wakeup\_source | Source of liveness execution (e.g., cron, operator, browser\_fallback). |
| dim\_channel | Target channel identifier (daily\_brief or revolution\_watch). |
| dim\_model\_route | Specific 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 Code | Classification | Description | Recoverability |
|---|---|---|---|
| ERR\_PROV\_429 | Rate Limit | Provider rate limits exceeded. | Auto-recover via Jitter Backoff11. |
| ERR\_PROV\_500 | Upstream | Provider API returned internal server error. | Auto-recover via Jitter Backoff. |
| ERR\_VAL\_EVID | Validation | Retained candidates lack sufficient verifiable URLs. | Operator intervention required. |
| ERR\_VAL\_LANG | Validation | Spanish and English text lack semantic parity. | Operator intervention required. |
| ERR\_SYS\_LOCK | Concurrency | Pipeline failed to acquire stage lock. | Auto-recover on next wakeup. |
| ERR\_CRON\_DEAD | Infrastructure | Heartbeat 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 Element | Public Status Page | Private Operator Console | Downloadable Support Bundle |
|---|---|---|---|
| Pipeline Stage (1-8) | Masked entirely as "Active" | Visible | Visible |
| Provider Response IDs | Hidden | Hidden | Visible |
| Prompts & Text Payloads | Hidden | Hidden | Redacted / Summarized |
| Source URLs under Review | Hidden | Visible | Visible |
| Filesystem Paths | Hidden | Hidden | Visible (Root paths sanitized) |
| Credentials/API Keys | Hidden | Hidden | Strictly Excluded |
| Internal Network IPs | Hidden | Hidden | Strictly Excluded |
| Anti-Abuse Thresholds | Hidden | Hidden | Visible |
| Health Code | Mapped to Public Taxonomy | Raw State Visible | Raw 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 Objective | SLI Numerator | SLI Denominator | Measurement Window | Target | Alert Threshold | Operator / User Consequence |
|---|---|---|---|---|---|---|
| Edition Publication Timeliness | Editions successfully published before 06:00 UTC | Total editions scheduled | 30 Days | 99.0% | \< 99.5% | Readers miss morning briefing. |
| Time to First Provider Poll | Jobs with ts\_provider\_create\_started \- ts\_local\_job\_created \< 2m | Total jobs created | 7 Days | 99.9% | \< 99.9% | Backlog buildup; slow starts. |
| Max Overdue Continuation | Polling cycles where ts\_actual\_poll \- ts\_next\_retry\_due \< 5m | Total polling cycles | 7 Days | 99.0% | \< 95.0% | Cron failure; jobs stall silently. |
| Provider Completion Latency | Responses consumed within 10m of provider completed state | Total completed responses | 30 Days | 99.5% | \< 98.0% | Wasted provider spend; stale news. |
| Local Validation Latency | Semantic and evidence validations completing \< 5m | Total validation attempts | 7 Days | 99.0% | \< 95.0% | Operator UI hangs during saving. |
| Publication Write Latency | Filesystem and database writes completing \< 10s | Total publication writes | 30 Days | 99.9% | \< 99.0% | Reader encounters 404 on release. |
| Status Freshness | Operator UI status polling lag \< 30s | Total active operator sessions | 24 Hours | 99.9% | \< 99.0% | Operator acts on stale, unsafe data. |
| Cron Heartbeat Freshness | Heartbeats with time delta \< 5m | Expected heartbeats (288/day) | 24 Hours | 99.9% | Missing \> 2 | Pipeline effectively dead. |
| Duplicate Generation | Provider requests yielding unique API output IDs | Total provider requests | 30 Days | 99.9% | \> 0.1% | Wasted budget; rate limits hit. |
| Duplicate Publication | Editions published exactly once per specific target date | Total published editions | 90 Days | 100% | \> 0% | Severe reputational and SEO damage. |
| Stranded Accepted Work | Provider jobs reaching a terminal state (not stuck \> 24h) | Total accepted provider jobs | 30 Days | 99.9% | \< 99.5% | Silent zombie jobs consuming DB. |
| Source Qualification Success | Candidates passing verifiable evidence binding checks | Total candidates processed | 30 Days | 95.0% | \< 90.0% | Hallucinated news blocks pipeline. |
| Operator Recovery Time | Mean time to successfully resolve a REPAIR NEEDED state | Total repair incidents | 30 Days | 90.0% | \> 30m | Extended delay for readers. |
| Cleanup Completion | Temporary JSON/text files successfully deleted post-publish | Total temp files created | 7 Days | 99.9% | \< 99.0% | Storage exhaustion over time. |
| Diagnostic Redaction | Support bundles successfully passing PII regex validation | Total support bundles generated | 90 Days | 100% | \> 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.
| Scenario | Symptoms & Confirmation Evidence | Immediate Containment & Safe Actions | Prohibited Actions & Escalation |
|---|---|---|---|
| 1\. Queued response with zero polls | Job 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 duration | Provider 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 consumed | Provider 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 missing | ts\_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 provider | Heartbeats 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 deployment | Public 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 mismatch | CONFIGURATION 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 failure | Pipeline 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 failure | ERR\_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 limit | ERR\_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 error | ERR\_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 candidates | Stage 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 abstains | Stage 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 parity | Stage 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 indexed | ts\_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 edition | RSS 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 responses | Cost 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 compromised | Anomalous 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 failure | ts\_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 overdue | ts\_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.
| Category | OAT Requirements |
|---|---|
| Cron & Wakeup | 1\. 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 & Network | 11\. 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 & Validation | 21\. 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. |
| Telemetry | 31\. 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 & Cleanup | 41\. 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 & Accessibility | 51\. 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