Semantic Systems / Language / Glyphs
Production Assurance Program for the InternationalIntelligence.org Daily Brief
Report summary
InternationalIntelligence.org should treat the Daily Brief as a reader-facing publication service , not as a successful PHP process, scheduler invocation, provider request, or validator run. The central production question is:
Key topics
- Semantic Systems / Language / Glyphs
- Semantic Systems
- Language
- Glyphs
- AI
- Runtime
- Privacy
- Research Archive
- Strategy
Research provenance
For citation, use the report title and canonical URL. Archival presence does not establish authorship or promote report statements into portfolio evidence.
Source availability: 20 citation markers in the source export have no recoverable source links. Those markers are omitted from this reader; any supplied bibliography and ordinary links remain. Check the original sources before relying on the cited claims.
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 SRE recommendation and research basis
InternationalIntelligence.org should treat the Daily Brief as a reader-facing publication service, not as a successful PHP process, scheduler invocation, provider request, or validator run. The central production question is:
Can an independent observer prove that the correct English and Spanish edition for the intended date was generated once, validated against a defined evidence policy, atomically published, consistently served by every public host and cache layer, and recoverable without repeating paid or externally visible work?
The project context describes a system intended to maintain one active process, an immutable target date, a monotonic revision sequence, one current provider operation, a single transition writer, shared bilingual state, atomic publication, and safe stale-worker recovery. It also specifies strict privacy constraints and the absence of direct access to code, infrastructure, databases, credentials, or private telemetry.
The recommended architecture has five mutually reinforcing controls:
- A machine-verifiable edition manifest becomes the publication proof. It binds the target date, publication event, English and Spanish artifact hashes, evidence-policy result, revision, release, and site instance.
- Compare-and-swap state transitions with leases prove that only the current revision and operation may advance the workflow. Old workers may finish computation but cannot commit state or publish.
- An append-only, hash-chained event ledger explains every reservation, provider interaction, retry, reconciliation, validation result, publication preparation, publication commit, correction, quarantine, and operator action without retaining prompts or provider bodies.
- Read-only production synthetics test the same public paths readers use while being structurally incapable of starting research, composition, publication, or paid provider work.
- A release-proof bundle records deterministic tests, concurrency races, crash matrices, package checksums, origin and browser smoke tests, scheduler proof, synthetic results, canary observations, and rollback readiness for every deployed release.
These controls close the component-test/production-assurance gap because they test relationships that syntax checks and isolated validators cannot establish: scheduler-to-supervisor continuity, provider completion-to-reconciliation latency, state-to-artifact agreement, bilingual identity, release uniformity, host uniformity, cache freshness, and crash-safe idempotency.
Selected research topic. Because the uploaded project brief specifies a concrete topic, no cross-domain topic-ranking exercise is necessary. The selected topic is production observability and release verification for a bilingual, scheduled, AI-assisted publication pipeline.
Source basis. The architecture is grounded primarily in current official standards and first-party engineering guidance:
| Primary source | What it standardizes or studies | Application to the Daily Brief | Limitation or tension |
|---|---|---|---|
| OpenTelemetry specification and semantic conventions | Common telemetry model, resource identity, traces, logs, metrics, and attributes | Correlate scheduler, provider, validation, publication, and status operations; distinguish service.version and service.instance.id | A full collector and tracing backend may be excessive for constrained PHP hosting. |
| W3C Trace Context | Interoperable traceparent and tracestate propagation | Carry one trace across HTTP scheduler callbacks, workers, origin requests, and internal provider adapters without embedding sensitive data | External trace headers are untrusted and must not contain personal or confidential information. |
| Prometheus metric guidance | Metric naming, base units, histograms, and label-cardinality discipline | Low-cardinality metrics for stage dwell, publication, locks, leases, retries, cache age, and recovery | Native histogram support may be limited in the chosen PHP stack; classic histograms are acceptable initially. |
| Google SRE Workbook | SLO documents, error budgets, alerting, and release policy | Convert late, inconsistent, or unrecoverable editions into explicit reliability budgets and change controls | Numerical targets must be calibrated from actual reader expectations and baseline data, not copied mechanically. |
| RFC 9111 | HTTP cache freshness, validation, cache keys, and invalidation | Verify that public status and publication pages are not stale or split across cache layers | Correct origin state does not guarantee every browser, CDN, or service worker displays current data. |
| OpenAI platform documentation | Provider data controls, asynchronous/background behavior, usage, and API object lifecycle | Design bounded reconciliation and a separately budgeted provider probe without persisting provider bodies in observability systems | Provider modes and retention characteristics can change; implementation must verify the exact API and account policy in use. |
The standards progression relevant to this design is:
timeline
title Standards and implementation timeline
2021 : W3C Trace Context Recommendation
: Portable traceparent and tracestate propagation
2022 : RFC 9111 published
: Current HTTP caching and freshness rules
2025 : OpenTelemetry semantic conventions expanded
: Stable service instance and service version identity
2026 : Daily Brief production-assurance program
: Publication manifests, state CAS, synthetics, chaos proof
W3C Trace Context became a Recommendation in November 2021, RFC 9111 standardized the current HTTP caching model in June 2022, and OpenTelemetry now defines stable service identity attributes such as service.instance.id and service.version.
Explicit assumptions and unspecified preferences.
| Item | Working assumption | Required owner decision |
|---|---|---|
| Editorial deadline | Represented as configurable variable D; no deadline is assumed | Select deadline model, timezone, grace period, weekends, and holidays |
| Target date | Editorial calendar date in an explicitly configured publication timezone | Confirm whether the target follows America/Chicago, UTC, or another editorial timezone |
| Storage | The state store supports either transactional compare-and-swap or an equivalent file-lock/revision mechanism | Identify database, filesystem, object store, and atomic-operation guarantees |
| Deployment | More than one release or instance may accidentally serve traffic | Confirm host, CDN, load balancer, origin, and shared-storage topology |
| Provider | Provider operations have a durable external identifier retrievable after ambiguous failures | Confirm the exact provider endpoint, polling model, retention, and idempotency support |
| Evidence policy | Counts and regional/corroboration requirements are configurable | Editorial owner defines hard floors, desired targets, and exception policy |
| Spanish content | English and Spanish must share one publication identity but may have different byte hashes | Confirm whether Spanish is translation, independently composed, or independently validated |
| Monitoring | Either OpenTelemetry or structured JSON can be added | Choose telemetry backend, retention, access controls, and paging system |
| Correctness | Automated evidence rules are necessary but cannot prove factual truth | Define human sampling, corrections, and editorial accountability |
| Public status | Must reveal only bounded operational information | Approve exact field allowlist and minimum update interval |
The largest evidence gap is that no production measurements are available. Therefore, stage thresholds below are initial engineering limits, not claims about the system’s current latency. The first 30 days should measure normal distributions, after which thresholds should be recalibrated without weakening hard safety invariants.
Service definition, failure taxonomy, SLIs, SLOs, and error budgets
Reader-perspective service definition. A Daily Brief edition is successful only when all of the following are true for the target date:
| Dimension | Reader-facing success criterion | Example of misleading “green” status |
|---|---|---|
| Availability | Canonical English and Spanish edition routes and required artifacts are retrievable | HTTP 200 serves yesterday’s cached edition |
| Freshness | The published target date satisfies the editorial promise relative to configured deadline D | Today’s route exists but points to an old target |
| Correctness | The edition passes hard schema, state, evidence, attribution, and publication-manifest validation | Fresh text contains unsupported claims or malformed citations |
| Consistency | Supervisor state, event ledger, publication pointer, artifacts, status endpoints, hosts, and caches agree | Supervisor says published, but the public package is absent |
| Evidence completeness | The edition meets hard floors for retained sources, selectable candidates, corroboration, and regional coverage | Composition completed from insufficient or one-sided evidence |
| Bilingual parity | English and Spanish have the same target, publication event, revision, correction generation, and manifest | English is corrected while Spanish remains on the earlier event |
| Recoverability | Crashes, ambiguous provider responses, stale leases, and partial publication are repaired within a bounded time without duplicate external work | Retrying after a timeout starts another full research job |
| Operator safety | Diagnosis and recovery are bounded, idempotent, privacy-safe, and auditable | An operator “retry” button silently starts a second paid provider request |
Availability, freshness, and correctness are independent. A page can be available but stale when a CDN, PHP cache, browser cache, or service worker returns a valid 200 response for an earlier revision. It can be fresh but incorrect when the target date is current but evidence validation was bypassed, regional requirements were missed, English and Spanish diverged, or unsupported claims passed through composition. RFC 9111 explicitly distinguishes response freshness from origin validity and recognizes that application-level mechanisms can still display old representations; therefore, HTTP success cannot substitute for edition identity and age checks.
Failure taxonomy.
| Failure class | Concrete examples | Proof needed |
|---|---|---|
| Trigger failure | Cron absent, wrong timezone, CLI path changed, scheduler invokes old release | Heartbeat age, expected-versus-actual schedule, scheduler release, target reservation event |
| Coordination failure | Stuck lease, overlapping cron, concurrent operator action, stale worker commits | Lease history, CAS rejection, lock contention, winning reservation, revision sequence |
| Provider lifecycle failure | Lost provider ID, successful create with lost response, completion not consumed, poll after replacement | Stable operation identity, create-attempt event, reconciliation lookup, poll history |
| Progress failure | Stage dwell excessive, retries repeat without count improvement, retained evidence discarded | Stage-age histogram, attempts, evidence deltas, no-progress alert |
| Validation failure | Evidence floor unmet, regional deficit, candidate not selectable, bilingual mismatch | Validation result codes and count summary |
| Publication failure | Partial write, failed rename, artifact absent, manifest mismatch, duplicate publication | Prepared/committed events, immutable content hashes, canonical pointer generation |
| Serving failure | Stale origin cache, CDN stale JSON, service worker stale, alternate-host split brain | Origin-versus-edge comparisons, Age, ETag, release and instance headers |
| Deployment failure | CLI and web versions differ, two releases serve traffic, schema drift | Release inventory, schema version, instance/version observations |
| Recovery failure | Repeated lease expiry, reconciliation loops, manual intervention, abandoned process still writable | Recovery-duration metrics, quarantine event, stale-transition rejection |
| Editorial failure | Unsupported claim, correction only in one language, incomplete regional representation | Editorial review record, correction generation, parity and evidence outcomes |
State and publication invariants. These are not error-budget objectives; they are correctness properties that every accepted transition and publication must satisfy.
| Invariant | Required rule |
|---|---|
| Single logical process | At most one nonterminal process owns a target date and publication namespace |
| Immutable target | target_date never changes after process initialization |
| Monotonic revision | Every successful transition changes revision from r to exactly r+1 |
| Current-operation uniqueness | At most one current provider or external-effect operation exists per process |
| Single transition writer | A transition commits only when process ID, expected revision, lease owner, and operation identity all match |
| Stale-worker exclusion | A stale or replaced worker may record an observation but cannot change current state or publish |
| Retention across retries | Valid retained evidence survives composition, validation, and publication retries |
| Shared bilingual identity | English and Spanish artifacts reference the same publication_event_id, target, revision, and correction generation |
| Atomic public visibility | Readers see either the prior complete edition or the new complete edition, never a mixed package |
| Idempotent publication | Recommitting an already committed manifest with identical hashes is a no-op |
| Content-addressed artifacts | Artifact names or manifests bind bytes to cryptographic hashes |
| Reconciliation before recreation | Ambiguous provider or publication outcomes are reconciled before new external work begins |
SLI definitions. Each SLI must be computed from authoritative machine events, edition manifests, or independent synthetics—not from a progress bar.
| SLI | Definition |
|---|---|
| Publication freshness | observation_time − effective_target_deadline, bounded below at zero; also report current_target_date − last_published_target_date in calendar days |
| Editions published by deadline | count(editions committed by D + grace) / count(expected editions) |
| Active-process age | now − process_initialized_at for the current nonterminal process |
| Stage dwell | now − entered_current_stage_at; completed-stage duration is transition end minus start |
| Scheduler-heartbeat age | now − last_valid_scheduler_heartbeat_at |
| Provider completion-to-reconciliation | provider_reconciled_at − provider_completed_at, or lower-bound estimate when completion time is unavailable |
| Evidence completeness | Weighted ratio of satisfied evidence rules; publishability requires every hard rule |
| Selectable-candidate count | Number of candidates passing extraction, relevance, recency, language, and source-safety criteria |
| Corroborated-candidate count | Candidates supported by the configured number and diversity of independent sources |
| Regional representation | Count and proportion of configured regions represented, with per-region minimum status |
| Bilingual parity | Fraction of probes where target, event ID, revision, correction generation, and manifest relationship agree |
| Status consistency across endpoints | Fraction of same-window observations whose process, target, revision, state, release, and publication identity agree |
| Status consistency across windows | Fraction of sequential observations that are monotonic and do not regress without an explicit rollback/correction event |
| Canonical-host correctness | Fraction of alternate-host requests redirected to the canonical origin and canonical requests served by the approved site identity |
| Artifact availability | Fraction of committed manifest artifacts retrievable and checksum-verifiable |
| Edition-hash agreement | Fraction of public artifacts whose observed hashes equal the committed manifest |
| Recovery time | healthy_recovery_verified_at − incident_or_failure_detected_at |
| Manual-intervention frequency | Operator mutation actions per edition and per rolling 30 days |
| Stale-transition rejection | Rejected stale writes divided by attempted transitions; count is both a safety proof and a contention signal |
| Lock contention | Failed or delayed lock acquisitions divided by reservations |
| Repeated no-progress attempts | Attempts with unchanged stage outcome and zero useful evidence delta |
| Cache age | Origin-generated timestamp age and HTTP Age, sampled separately by endpoint, host, and cache layer |
Deadline models. The owner should choose one model and publish it as an editorial contract.
| Model | Objective example | Best fit | Risk |
|---|---|---|---|
| Fixed local deadline | “Edition for target T is committed by D(T) plus 15-minute grace” | Readers expect a morning edition at a predictable time | Requires holiday, DST, and missed-day rules |
| Source-cutoff-relative | “Edition is committed within 90 minutes of editorial source cutoff” | Research cannot begin until a defined collection window closes | Less intuitive to readers |
| Rolling freshness | “A current edition is never more than 24 hours old” | Continuous publication without a strict daily launch moment | Can conceal repeated lateness near the rolling limit |
| Dual objective | Fixed deadline for initial edition plus correction latency SLO | Formal daily edition with post-publication corrections | More metrics and operational policy |
| Business-calendar objective | Deadline applies only on configured publication days | Weekday-only or holiday-aware operation | Calendar configuration becomes critical production state |
Recommended initial SLO tiers. Targets should be reviewed after the baseline period. Google’s SRE guidance treats the error budget as 1 − SLO, recommends documenting measurement caveats, and uses budget exhaustion to control release velocity rather than to punish teams.
| Tier | Measurement window and initial target | Error budget | Exclusions and maintenance | Alerting and reporting |
|---|---|---|---|---|
| Reader-facing freshness | Rolling 90 expected editions; 99% committed by selected deadline plus grace | 1% of expected editions; at 90 editions, 0.9 late editions | Only predeclared no-publication days; maintenance does not exclude a reader-visible miss unless the editorial promise was changed in advance | Warning at deadline, page at deadline plus critical grace; weekly and quarterly review |
| Workflow progress | Rolling 28 days; 99% of stage observations below stage limit; no process above absolute maximum | 1% observation budget, but hard maximum violations always page | Approved load/chaos windows tagged before execution | Multi-window burn alerts plus direct stuck-state alert |
| Recovery | Rolling 90 days; 95% recovered within 15 minutes and 99% within 60 minutes | 5% and 1% respectively | Planned failover drills reported separately but not silently discarded | Page for breached recovery timer; monthly incident distribution |
| Status consistency | Rolling 28 days; 99.99% of paired public observations consistent | 0.01% paired-probe budget | Only monitor defects proven by independent control probe | Immediate page for identity or publication disagreement |
| Editorial evidence | Rolling 90 editions; 98% meet desired evidence target; 100% meet hard publication floor | 2% may use approved exception; zero budget below hard floor | Explicitly approved breaking-news exception with named editor and expiry | Ticket or warning for desired-target miss; block publication below hard floor |
| Bilingual parity | 100% commit-time parity; 99.99% public retrieval parity | Zero commit-time budget; 0.01% transport budget | None for commit parity; verified monitor faults only for retrieval | Immediate publication block before commit; immediate page after commit |
| Artifact integrity | 100% manifest/hash agreement for committed editions | Zero | None | Immediate page and quarantine |
| Operator safety | Fewer than 2 mutating interventions per 30 editions; 100% operator actions audited | One excess-intervention event triggers review; zero unaudited actions | Approved training environment only | Weekly trend; page only for unsafe or unaudited mutation |
A 99% deadline SLO over 90 expected editions permits only 0.9 late editions. One late edition therefore consumes approximately 111% of that period’s numerical budget:
xychart-beta
title "Ninety-edition freshness budget consumption at a 99% SLO"
x-axis "Late editions" [0, 1, 2, 3]
y-axis "Error budget consumed (%)" 0 --> 350
bar [0, 111, 222, 333]
This arithmetic shows why deadline-based services should combine a rolling SLO with a practical incident policy. A single late edition may exhaust the formal 90-edition budget, but the response should be a temporary reliability/change focus, not indiscriminate operational paralysis. Burn-rate alerts should be tuned to the objective and event frequency; Google’s guidance cautions that extremely high or low goals can make generic burn thresholds ineffective.
Initial stage limits. Before baseline measurements exist, configure stage-specific limits rather than one process timeout:
| Stage | Warning | Critical | Absolute safety action |
|---|---|---|---|
| Initialization/reservation | 2 minutes | 5 minutes | Release expired reservation if no external effect began |
| Primary research | 20 minutes | 45 minutes | Reconcile provider before retry; quarantine after repeated ambiguity |
| Supplemental repair | 15 minutes | 30 minutes | Stop when hard attempt or cost ceiling is reached |
| Composition | 10 minutes | 20 minutes | Retry composition from retained evidence; never restart research automatically |
| Final validation | 5 minutes | 10 minutes | Quarantine invalid candidate package |
| Publication preparation | 2 minutes | 5 minutes | Remove only unreferenced temporary files |
| Publication commit | 30 seconds | 2 minutes | Reconcile manifest, pointer, and ledger before any new commit |
| Cleanup | 5 minutes | 15 minutes | Cleanup failure must not unpublish a valid edition |
| Whole active process | 60 minutes | 120 minutes | Quarantine and require bounded reconciliation |
The rationale is operational separation: a provider stage may legitimately be much longer than a local state transition, whereas a two-minute publication commit almost certainly indicates a lock, storage, or partial-write problem.
Metrics, structured events, logs, and trace correlation
Metric design rules. Use prefix daily_brief_, SI/base units, counters for cumulative events, gauges for current state, and histograms for distributions. Prometheus recommends base units such as seconds and warns that every unique label combination creates a separate time series; unbounded values such as user identifiers must not be labels.
Counters answer “how many happened?” and never decrease except on process restart. Gauges answer “what is true now?” and may rise or fall. Histograms answer “how is duration or size distributed?” and permit SLO queries such as the fraction below a stage limit. Prometheus currently recommends native histograms when supported, while noting that library and exposition support varies; classic histograms are a sound initial choice for constrained PHP deployments.
Low-cardinality namespace.
| Metric | Type | Allowed labels and limits | Meaning |
|---|---|---|---|
daily_brief_active_process | Gauge | environment ≤4 | 1 when a nonterminal process exists |
daily_brief_target_lag_days | Gauge | environment | Calendar-day lag between current expected target and last committed target |
daily_brief_process_age_seconds | Gauge | environment | Current active-process age |
daily_brief_stage_age_seconds | Gauge | stage ≤10, environment | Current dwell of the active stage |
daily_brief_stage_duration_seconds | Histogram | stage ≤10, result ≤5 | Completed-stage duration |
daily_brief_supervisor_revision | Gauge | environment | Current monotonic revision |
daily_brief_active_operation | Gauge | operation ≤8 | One-hot current operation class; never label with operation ID |
daily_brief_provider_job_age_seconds | Gauge | provider ≤3, operation_kind ≤4 | Age of the current durable provider job |
daily_brief_provider_poll_eligible | Gauge | provider ≤3 | Whether polling is currently allowed |
daily_brief_provider_polls_total | Counter | provider ≤3, result ≤8 | Poll results: pending, completed, failed, throttled, ambiguous, ineligible |
daily_brief_attempts_total | Counter | stage ≤10, outcome ≤8 | Attempt totals by stage/outcome |
daily_brief_retained_candidates | Gauge | environment | Currently retained valid candidates |
daily_brief_retained_sources | Gauge | environment | Currently retained source records |
daily_brief_selectable_candidates | Gauge | environment | Candidates eligible for composition |
daily_brief_corroborated_candidates | Gauge | environment | Candidates meeting corroboration policy |
daily_brief_region_count | Gauge | region fixed allowlist ≤12 | Qualified items per configured region |
daily_brief_publications_total | Counter | result ≤6, language ≤3 | Prepared, committed, no-op, corrected, failed |
daily_brief_publication_artifact_mismatches_total | Counter | mismatch ≤8 | Missing, hash, event, target, language, pointer mismatch |
daily_brief_stale_transitions_rejected_total | Counter | stage ≤10, reason ≤6 | CAS or lease rejection of stale writes |
daily_brief_lock_contention_total | Counter | lock_scope ≤5, result ≤4 | Lock acquisition contention |
daily_brief_lease_expiries_total | Counter | stage ≤10 | Expired stage leases |
daily_brief_scheduler_heartbeat_timestamp_seconds | Gauge | scheduler ≤3, release_role ≤3 | Unix time of last valid scheduler heartbeat |
daily_brief_scheduler_heartbeat_age_seconds | Gauge | scheduler ≤3 | Derived scheduler age |
daily_brief_cache_age_seconds | Histogram | layer ≤5, endpoint_class ≤6, host_role ≤3 | Observed origin, CDN, browser, or service-worker age |
daily_brief_status_mismatches_total | Counter | dimension ≤10, endpoint_pair ≤8 | Cross-endpoint/window disagreement |
daily_brief_bilingual_mismatches_total | Counter | dimension ≤8 | Target, event, revision, correction, manifest mismatch |
daily_brief_operator_actions_total | Counter | action ≤12, result ≤6 | Audited operator actions |
daily_brief_process_quarantines_total | Counter | reason ≤10 | Process quarantines |
daily_brief_recovery_duration_seconds | Histogram | failure_class ≤12, mode ≤4 | Detection-to-verified-recovery time |
daily_brief_no_progress_attempts_total | Counter | stage ≤10 | Retries with no useful count or state improvement |
daily_brief_provider_cost_units_total | Counter | provider ≤3, operation_kind ≤4 | Provider usage in configured cost units |
daily_brief_release_observations | Gauge | release_slot ≤3, component ≤4 | Count or presence of approved/current/previous release observations |
daily_brief_site_instance_observations | Gauge | instance_slot ≤4, host_role ≤3 | Presence of expected versus unexpected instance identities |
Cardinality budget. A practical initial budget is fewer than 2,000 active series for the service, fewer than 12 values for any label, and no label whose value is created per process, provider request, source, article, trace, browser, operator, or reader. process_id, operation_id, event_id, publication hashes, provider request IDs, URLs, source domains, exception messages, and worker IDs belong in structured events or trace attributes, not metric labels.
Individual incidents are linked through:
- a low-cardinality alert label such as
stage="publication"; - an exemplar containing a trace ID where the metrics backend supports exemplars;
- a dashboard link that queries the event store by incident time and pseudonymous process reference;
- a trace or event correlation ID stored outside the metric label set.
Structured state-transition event schema.
| Field | Form and privacy rule |
|---|---|
schema_version | Fixed small integer |
event_id | Random UUID/ULID; internal only or truncated/HMAC-pseudonymized publicly |
previous_event_hash | Prior ledger hash for the process or global stream |
process_id | Internal opaque ID; public reports use an HMAC-derived short reference |
target_date | ISO date |
from_state, to_state | Enumerated states |
prior_revision, new_revision | Integers; successful transition requires new=prior+1 |
operation_id | Opaque external-effect identity; redact or pseudonymize in broad-access logs |
site_instance_id | OTel-compatible opaque instance identity |
release | Immutable build or deployment identifier |
trigger_type | scheduler, worker, operator, reconciler, release_probe |
worker_id | Ephemeral internal identity; never public |
expected_revision | Revision used for CAS |
result_code | Bounded enum such as committed, stale_revision, lease_lost, no_op |
error_class | Redacted enum, never raw exception text |
started_at, ended_at, duration_ms | UTC timestamps and duration |
external_effect | Boolean |
reconciliation_required | Boolean |
evidence_before, evidence_after | Counts only: retained, selectable, corroborated, regions |
publication_reference | Manifest ID and content hash, not a private path |
trace_id, span_id | OpenTelemetry/W3C correlation values |
event_integrity_hash | Hash or HMAC over canonical event fields and previous hash |
Sample redacted event.
{
"schema_version": 1,
"event_id": "evt_01K1EXAMPLE8R7Z",
"previous_event_hash": "sha256:91a4…f208",
"process_id": "proc_internal_opaque",
"target_date": "2026-08-01",
"from_state": "research_reconciling",
"to_state": "evidence_ready",
"prior_revision": 18,
"new_revision": 19,
"operation_id": "op_pseudonym_f3a9",
"site_instance_id": "site_7c2f",
"release": "2026.08.01+8ae73a",
"trigger_type": "reconciler",
"worker_id": "worker_ephemeral_12",
"expected_revision": 18,
"result_code": "committed",
"error_class": null,
"started_at": "2026-08-01T11:14:03.120Z",
"ended_at": "2026-08-01T11:14:04.774Z",
"duration_ms": 1654,
"external_effect": false,
"reconciliation_required": false,
"evidence_before": {
"retained_candidates": 9,
"selectable_candidates": 5,
"corroborated_candidates": 3,
"represented_regions": 3
},
"evidence_after": {
"retained_candidates": 14,
"selectable_candidates": 9,
"corroborated_candidates": 7,
"represented_regions": 5
},
"publication_reference": null,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"event_integrity_hash": "hmac-sha256:05d7…b0ce"
}
Append-only privacy-preserving ledger. Canonicalize the event JSON, omit the integrity field, and compute:
event_integrity_hash =
HMAC-SHA256(audit_key,
previous_event_hash || canonical_event_bytes)
The ledger stores only classifications, timestamps, counts, hashes, and opaque identifiers. It must never contain prompts, article text, source excerpts, provider response bodies, credentials, full private paths, raw account identifiers, reader information, cookies, IP addresses, or unredacted exceptions. Store a provider object identifier only when operationally necessary, encrypt it at rest, and expose only a pseudonymous reference to normal dashboards.
The ledger should be append-only at the application level and periodically checkpoint its current head hash to a separately protected location. A snapshot is a performance optimization; the ledger and immutable publication manifests provide reconstruction evidence. Because ledger and snapshot writes may fail independently, every transition follows a recoverable protocol:
- calculate the proposed transition against expected revision;
- append a
transition_intentor transactional event; - commit the new snapshot using CAS;
- append
transition_committed; - on restart, reconcile any unmatched intent or snapshot revision;
- never infer that external work must be repeated merely because the final audit event is missing.
Where a database supports an atomic transaction, the snapshot and event row should commit together. Where it does not, the protocol above makes ambiguity explicit and recoverable.
OpenTelemetry trace design. Use one trace per scheduler invocation, operator recovery action, or synthetic session, with linked traces for provider operations that outlive the initiating process. Recommended spans are:
daily_brief.scheduler.tick
daily_brief.supervisor.reserve
daily_brief.provider.create
daily_brief.provider.poll
daily_brief.provider.reconcile
daily_brief.evidence.validate
daily_brief.research.supplement
daily_brief.compose
daily_brief.final_validate
daily_brief.publish.prepare
daily_brief.publish.commit
daily_brief.cleanup
daily_brief.status.render
Set OTel resource attributes including:
service.namespace = "internationalintelligence"
service.name = "daily-brief"
service.instance.id = "<opaque per-instance ID>"
service.version = "<immutable release>"
deployment.environment.name = "production"
OpenTelemetry defines service.instance.id as unique for each concurrent instance of the same logical service and service.version as the exact version identifying the artifact. These attributes directly support multiple-instance and deployment-drift detection.
Use W3C traceparent for HTTP propagation. Do not place process IDs, source information, account details, or personal information in tracestate; the W3C specification expressly warns against personal or sensitive trace data. Treat incoming trace headers as untrusted, regenerate or sanitize context at the public trust boundary, and preserve only approved internal correlation.
For non-OTLP JSON logs, use top-level trace_id, span_id, and trace_flags; this matches OpenTelemetry’s stable compatibility guidance.
Constrained-hosting alternative. If a collector and tracing backend are not feasible, emit one structured JSON line per event to an append-only daily file or remote log sink:
{
"ts": "2026-08-01T11:14:04.774Z",
"severity": "INFO",
"event_name": "daily_brief.transition",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"process_ref": "p_6C9A1D",
"target_date": "2026-08-01",
"revision": 19,
"stage": "evidence_ready",
"result": "committed",
"release": "2026.08.01+8ae73a",
"site_instance": "site_7c2f",
"duration_ms": 1654,
"error_class": null
}
A periodic exporter can derive counters and gauges from these events. The essential requirement is stable semantics and correlation, not a particular observability vendor.
Causal model.
flowchart TD
A[Scheduler heartbeat] --> B{Current target reserved?}
B -- No --> C[Create one process and immutable target]
B -- Yes --> D[Load current revision and operation]
C --> E[Reserve stage using CAS and lease]
D --> E
E --> F{External operation already exists?}
F -- Yes --> G[Poll or reconcile same operation]
F -- No --> H[Create operation and persist identity]
H --> G
G --> I[Validate and retain evidence]
I --> J{Hard evidence floor met?}
J -- No, repair allowed --> K[Supplement only deficits]
K --> I
J -- No, limits reached --> L[Quarantine or editorial exception]
J -- Yes --> M[Compose from retained evidence]
M --> N[Final bilingual validation]
N --> O[Prepare immutable artifacts and manifest]
O --> P[Atomically switch canonical publication pointer]
P --> Q[Verify public EN and ES hashes]
Q --> R[Close process and retain audit proof]
S[Stale worker] --> T[Expected revision mismatch]
T --> U[Reject transition; no external retry]
V[Lost response] --> W[Mark reconciliation required]
W --> G
X[Stale cache] --> Y[Synthetic observes old event or Age]
Y --> Z[Purge or revalidate cache; never republish]
Every control in the diagram follows the same contract:
| Control | Failure detected | Duplicate-work prevention | Evidence emitted | Safe action | False-positive or operational risk |
|---|---|---|---|---|---|
| CAS revision check | Stale worker or concurrent writer | Losing writer cannot commit | Stale-transition event and counter | Reload and reconcile | Clock-independent; low false-positive risk, but schema bugs can reject valid work |
| Durable operation identity | Lost provider ID or ambiguous create | Reconcile existing operation before recreate | Operation-created/reconciled event | Poll/retrieve current operation | Provider retention may expire before reconciliation |
| Evidence retention | Composition or publication retry | Retry downstream stage without new research | Evidence hash/count delta | Reuse retained set | Corrupt retained data must be detected by checksum |
| Immutable package and pointer switch | Partial or mixed publication | Existing package is reused by hash | Prepared/committed manifest events | Complete or roll back pointer | Filesystem atomicity may differ across mounts |
| Bilingual shared manifest | Language divergence | One commit owns both languages | Manifest parity result | Block or revert commit | Translation completion may legitimately lag before commit, never after |
| Synthetic identity comparison | Cache, host, release, or instance split | Read-only; no workflow mutation | Probe observation | Purge/revalidate/escalate | Monitoring node may see a regional cache anomaly |
| Quarantine | Repeated ambiguous or unsafe state | Stops automated retries and external effects | Quarantine reason/event | Human reconciliation | Overuse can turn recoverable issues into manual toil |
Dashboards and alert catalog
Dashboard: Editorial Freshness. The first screen should answer whether readers have the right edition, not whether the worker is busy.
| Panel | Required display |
|---|---|
| Current expected target | Editorial-calendar target and configured timezone |
| Last committed target | Target, publication event, revision, commit time |
| Target lag | Calendar days and deadline-relative minutes |
| Publication deadline | Model, D, grace, holiday rule |
| Recent success | On-time percentage for 7, 28, and 90 editions |
| Error budget | Remaining freshness budget and projected exhaustion |
| Evidence completeness | Hard-floor pass plus desired-score ratio |
| Evidence counts | Retained, selectable, corroborated, represented regions |
| Bilingual parity | English/Spanish target, event, revision, correction generation |
| Edition integrity | Manifest ID and current artifact verification state |
| Correction status | Current correction generation, language coverage, age |
| Public-serving state | Canonical, alternate host, origin, and CDN observed edition IDs |
Color must not be driven by HTTP 200. “Green” requires current target, valid manifest, both languages, expected hashes, and bounded public age.
Dashboard: Workflow and Provider.
| Panel | Required display |
|---|---|
| Process identity | Bounded process reference, immutable target, initialized time |
| State and revision | Current state, revision, last transition, transition writer |
| Stage dwell | Current age versus warning/critical limit and recent percentile |
| Lease | Owner class, expiry, renewal count; no raw worker identifier in broad view |
| Active operation | Operation class and pseudonymous operation reference |
| Provider lifecycle | Create status, durable identifier present, provider state, age |
| Polling | Last poll, next eligible poll, result, backoff, reconciliation requirement |
| Attempts | Per-stage attempts and no-progress attempts |
| Evidence progression | Counts over time rather than current count alone |
| Deficits | Missing corroboration, candidates, regions, or source diversity |
| Retention | Hash of retained evidence set and whether downstream retries reused it |
| Stale writes | Recent stale-transition rejections with revision context |
| Locks and leases | Contention, expiry, and overlap trends |
| Cost | Budget used, projected ceiling, and blocked-operation status |
Dashboard: Scheduler, Origin, Cache, and Release.
| Panel | Required display |
|---|---|
| Scheduler | Last heartbeat, expected interval, missed runs, scheduler release |
| CLI/web versions | Current CLI release, web release, schema version |
| Site instances | Unique instance IDs by host and observation point |
| Releases serving traffic | Approved, previous, unexpected; observations over time |
| Canonical host | Redirect chain, scheme, host, and mutation-gate result |
| Origin status | Origin event, revision, generated timestamp |
| Cache status | Age, ETag, Last-Modified, cache-control, revalidation result |
| CDN | Edge locations sampled and edition identity by edge |
| Service worker | Script version, controlled-client version, cache generation |
| Artifacts | Manifest, English artifact, Spanish artifact, checksums |
| Storage | Writable staging area, atomic-rename self-test, free capacity |
| State backend | Read/write doctor, schema compatibility, lock/CAS health |
Alert catalog. Threshold variables are configurable:
S = expected scheduler interval
D = editorial deadline
G = publication grace
M = maximum active-process age
Tstage = critical stage threshold
Cprovider = configured provider cost ceiling
| Alert | Condition and evaluation | Severity | Likely causes and false-positive controls | Required context and first action | Escalation, safe automation, and prohibited automation |
|---|---|---|---|---|---|
| No scheduler heartbeat | Warning at age >2S+jitter for 2 evaluations; critical at >3S+jitter | SEV-2 if target at risk; otherwise SEV-3 | Cron disabled, wrong path, old CLI release, host outage. Suppress only for declared maintenance; account for scheduler jitter | Show last heartbeat, expected invocation, CLI/web release, current target. Run read-only scheduler doctor | Escalate to hosting when cron never executes. Safe: one idempotent supervisor tick if no active reservation and policy permits. Never start provider work directly from the monitor |
| Active process too old | process_age > M for 5 minutes | SEV-2 | Stuck stage, lost operation, dead worker. Exclude intentionally quarantined process from paging but keep visible | Read process report; identify stage, lease, operation, last progress | Safe: enqueue reconciliation only. Never abandon or create replacement automatically while an external effect may exist |
| Stage dwell too long | stage_age > Tstage for 2 evaluations | SEV-2/3 by stage | Slow provider, lock, filesystem, validation loop. Use stage-specific thresholds and baseline percentiles | Inspect last event, lease, next eligible poll, attempt and evidence deltas | Safe: poll if eligible or expire a lease with no external effect. Never repeat research merely because a timer elapsed |
| Provider completed but not consumed | Provider terminal-complete observation and no reconciliation transition within 10 minutes | SEV-2 | Poller absent, lost operation linkage, stale lease, deployment mismatch. Require two consistent completion observations | Show operation ref, completion observation time, current process/revision | Safe: reconciliation job for same operation. Never create a new request |
| Repeated lease expiry | At least 3 expiries for same process/stage in 30 minutes | SEV-2 | Worker crash, runtime timeout, lease too short, clock anomaly | Show lease durations, renewals, worker release, process state | Safe: quarantine after third expiry. Never lengthen lease indefinitely or run two workers |
| Evidence counts not improving | Three attempts or 20 minutes with zero increase in selectable/corroborated counts while deficit remains | SEV-3; SEV-2 near deadline | Repeated poor source results, validator regression, full-research loop. Exclude attempts intentionally marked “validation only” | Show count timeline, deficits, retained evidence hash, attempt classes | Safe: switch to deficit-targeted supplementation or quarantine. Never discard retained evidence automatically |
| Target overdue | Warning at D; critical at D+G; SEV-1 at configured reader-impact ceiling | SEV-2, possibly SEV-1 | Scheduler, workflow, provider, validation, publication, serving | Show target, last committed edition, current stage, recovery ETA band | Safe: page and freeze nonessential deploys. Never publish an invalid or partial edition to satisfy freshness |
| Supervisor published but artifact absent | State says committed/published but manifest or required artifact fails two independent checks | SEV-1 | Partial write, wrong path, permissions, deleted file, storage split | Show manifest, pointer, expected hashes, origin versus edge result | Safe: point back to prior known-good complete manifest if atomic rollback is proven. Never synthesize missing language content |
| Artifact exists but supervisor is not published | Complete prepared package exists but state remains precommit for more than 2 minutes | SEV-2 | Crash between preparation and state/pointer commit | Verify package hash, target, revision, ledger intent | Safe: reconcile and commit only if exact expected manifest matches. Never infer validity from file existence alone |
| English and Spanish event IDs differ | Any committed or public paired observation differs for two probes | SEV-1 | Split publication, stale language cache, correction applied to one side | Show both event IDs, targets, revisions, hashes, cache ages | Safe: revert both to last shared manifest or purge verified stale cache. Never rewrite one language alone |
| Canonical and alternate hosts show different site instances | Two consecutive paired probes observe incompatible instances or releases | SEV-1/2 | DNS drift, alternate origin, split deployment, host-header routing | Show resolved endpoints, redirect chain, site/release headers | Safe: force alternate host to redirect at edge. Never permit mutations on the alternate host |
| Public status older than origin state | Public generated/event revision behind origin beyond cache TTL plus 2 minutes | SEV-2 | CDN cache, PHP cache, service worker, incorrect cache key | Compare origin and public ETag, Age, event, revision | Safe: targeted purge or forced revalidation. Never republish the edition |
| Multiple releases serve traffic | More than one release observed for 10 minutes outside declared canary | SEV-2; SEV-1 when schemas differ | Partial deployment, stale PHP workers, multiple origins | Show release-by-host/instance and schema versions | Safe: remove unexpected instance or complete rollback. Never allow both releases to mutate state |
| Repeated operator intervention | More than 2 mutations on one process or more than 3 interventions in 7 days | SEV-3/problem-management | Automation gap, unclear runbook, recurring storage/provider issue | Show action types, outcomes, operator-independent recurrence | Safe: open reliability problem and freeze risky changes. Never automate the previously manual action without idempotency proof |
| Lock contention spike | More than 10% of reservations contend over 15 minutes or five consecutive failures | SEV-3/2 | Overlapping cron, hung writer, dual releases, slow state backend | Show contenders by trigger class and release, not raw worker IDs | Safe: suppress duplicate scheduler ticks and reconcile lock owner. Never delete a live lock without lease/revision proof |
| Stale-transition rejection spike | More than 20 in 15 minutes or more than 5/minute | SEV-3/2 | Old release, overlapping workers, replaying queue, short leases | Show expected/current revisions, stages, releases | Safe: stop old worker population. Never weaken CAS checks to clear the alert |
| Provider cost budget nearing limit | 80% monthly/daily ceiling warning; 95% critical | SEV-3/2 | Retry storm, repeated research, larger-than-expected workload | Show operations by class, reconciliations, cost per edition | Safe: block new primary/supplemental requests while allowing poll/reconcile and local completion. Never cancel completed work or delete operation IDs automatically |
| Repeated full research despite retained evidence | Primary-research attempt count >1 while retained evidence is nonzero and no explicit invalidation event exists | SEV-2 | Retry path restarts entire pipeline, retention bug | Show retained-set hash and attempt history | Safe: block new research and resume downstream stage. Never erase retained data to make the state “clean” |
| Publication correction applied to one language | Correction generation or event differs after correction window | SEV-1 | Language-specific deployment/cache/pointer failure | Show prior/current shared manifests and language observations | Safe: restore last shared generation or complete the already validated pair atomically. Never expose a one-language correction |
| Publication/file hash mismatch | Public bytes differ from manifest on two independent fetches | SEV-1 | Corruption, stale file, wrong cache object, unauthorized change | Show manifest hash, observed hash, host/layer, ETag | Safe: remove corrupted generation from canonical pointer. Never “fix” the manifest to match unverified bytes |
| Canonical mutation gate failure | Alternate host or public synthetic route reports mutation could reach application writer | SEV-1 | Webserver rule drift, host validation regression | Show method, host, edge decision, release | Safe: disable mutation routes or enforce canonical host at edge. Never test with real credentials or a live mutation |
| Scheduler/web release drift | CLI release differs from canonical web release longer than deploy grace | SEV-2 | Cron invokes old path, incomplete deployment | Show CLI, web, schema, site instance | Safe: point scheduler to approved release after doctor test. Never execute migration or workflow advancement blindly |
Alert design principle. Alerts should page on reader impact, imminent deadline impact, violated hard invariants, or inability to recover—not on every retry or provider pending status. Multi-window burn alerts suit high-volume probe SLIs; direct state alerts are necessary for once-per-day publication events because a single miss can consume an entire formal budget.
Deterministic, integration, concurrency, and chaos test architecture
Test-layer matrix.
| Layer | Method | Failures detected | Duplicate-work protection proved | Evidence artifact | Operational risk |
|---|---|---|---|---|---|
| Pure state-model tests | Table-driven state transition tests | Illegal state transitions, target mutation, revision skips | Transition preconditions | Machine-readable invariant report | Low; model can diverge from implementation |
| Property-based invariant tests | Generate random valid/invalid event sequences | Rare interleavings and sequence edge cases | Idempotency and stale-write rejection | Seed, minimized failing sequence | Test generator may omit real storage behavior |
| Deterministic provider fixtures | No-network adapter with scripted accepted/pending/completed/failed/ambiguous outcomes | Lost IDs, polling errors, completion not consumed | Same operation reconciled | Fixture transcript excluding content | Fixture semantics can lag provider changes |
| Multi-process races | Barrier-controlled worker processes against real test store | Dual reservations, lock races, revision conflicts | Exactly one winning writer | Race schedule and final ledger | Flaky unless synchronization is deterministic |
| Crash injection | Kill after every persisted or external-effect boundary | Partial events, snapshots, artifacts, pointer updates | Reconciliation before recreation | Crash-point matrix | Requires isolated test storage |
| Storage partial-write tests | Faulting filesystem/database adapter | Truncated files, failed fsync/rename, half transactions | Immutable temp and pointer protocol | Checksums and recovery transcript | Must not run on production storage |
| Stale-worker and lease tests | Pause worker past lease, then resume | Late commit, old provider result | CAS and operation matching | Rejection event | Clock simulation must be controlled |
| Scheduler overlap/missed-run tests | Simultaneous ticks and skipped schedule slots | Duplicate process, absent catch-up | Idempotent target reservation | Scheduler event sequence | Schedule model must handle DST |
| HTTP cache tests | Origin, reverse-proxy, and mock-CDN layers | Incorrect cache key, stale status, missing invalidation | Purge/revalidation without republish | Headers and body identity comparison | Cache behavior varies by provider |
| Service-worker tests | Browser automation with old/new worker generations | Client-side stale status/artifacts | Versioned cache namespaces | Browser trace and worker version | Browser-specific timing |
| Browser multi-tab tests | Two tabs on old/new revisions; background throttling | Regressing status, duplicate UI action, stale tab | UI actions carry expected revision and idempotency key | Browser event log | Headless behavior may differ from mobile |
| Offline/online tests | Disconnect during poll/status/publication view | Stale UI treated as live, retry storms | Client only re-reads status | Network trace | Does not test server failure |
| Bilingual tests | Pairwise manifest and semantic-rule checks | Target/event/correction mismatch | One bilingual publication transaction | Pair-validation report | Semantic translation quality still needs editorial review |
| Package safety | Clean extraction, traversal/symlink rejection, checksums, byte comparison | Unsafe ZIP, hidden files, modified build | Release identified by manifest/hash | Package inventory and hashes | Platform permissions can alter metadata |
| Loopback HTTP smoke | Serve release locally and exercise canonical routes | PHP bootstrap/routing/header errors | No provider adapter enabled | HTTP transcript | Does not prove external DNS/CDN |
| Production synthetics | Read-only external probes | Deployment, scheduler, cache, host, artifact problems | No mutation capability | Signed observation bundle | Regional false positives |
| Controlled provider probe | Separate state namespace, explicit budget | Provider authentication/connectivity | Cannot write publication state | Probe status and cost | Paid call and provider retention implications |
Deterministic no-network end-to-end proof. Implement this as seven phases covering the twelve required lifecycle events.
| Phase | Scenario and injected outcome | Required assertions |
|---|---|---|
| Initialization and reservation | Initialize target T; race two research reservations | Exactly one process ID; target immutable; initial revision known; exactly one winning reservation; loser receives stale/conflict result; no network adapter invoked |
| Primary research and partial evidence | Fixture simulates accepted operation, background completion, and partial but valid evidence | One durable operation ID; operation persisted before polling; valid evidence retained; evidence hash recorded; revision strictly increments by one; provider create count is exactly one |
| Supplemental repair | Fixture adds only missing corroboration and regions | Supplemental attempt targets explicit deficits; retained evidence remains byte-identical; selectable/corroborated/region counts improve; no second primary research call |
| Composition failure and retry | First composition fixture fails deterministically; stale worker later submits old result; second composition succeeds | Composition failure changes state without discarding evidence; retry uses same retained-set hash; primary and supplemental call counts do not increase; stale worker is rejected by expected revision; revision never regresses |
| Final validation | English/Spanish package passes schema, evidence, and parity validation | Both languages bind to same target and proposed publication event; language-specific content hashes may differ; manifest relationship and correction generation agree; hard evidence floor passes |
| Interrupted publication and atomic recovery | Write temporary package and ledger intent, then crash before or during pointer switch; restart reconciler | Readers continue seeing prior complete edition or new complete edition, never a mixed pair; corrupt/uncommitted temp package is not public; recovery reuses prepared package when hash matches; publication hash remains stable |
| Publication, cleanup, and duplicate no-op | Commit shared manifest, verify public artifacts, run cleanup, then repeat publication command | One committed publication event; English/Spanish event IDs equal; artifact hashes equal manifest; cleanup removes only unreferenced temporary data; duplicate publication returns no-op, changes no bytes, revision, pointer, event ID, or external-call count |
Global assertions.
count(distinct process_id for target T) = 1
target_date(process) remains T for all events
new_revision = prior_revision + 1 for every committed transition
provider_primary_create_count = 1
winning_reservation_count per stage/revision = 1
retained_evidence_hash before composition failure =
retained_evidence_hash after composition retry
stale_transition_commit_count = 0
stale_transition_rejection_count >= 1
publication_manifest_hash before duplicate =
publication_manifest_hash after duplicate
english.publication_event_id = spanish.publication_event_id
network_socket_attempt_count = 0
Enforce the final condition at the operating-system or test-runtime boundary, not merely with a mock: disable DNS and outbound sockets, make the provider adapter throw on any network attempt, and assert the adapter’s call transcript contains only deterministic fixture operations.
Concurrency race suite.
| Race | Controlled interleaving | Pass criterion |
|---|---|---|
| Cron versus cron | Both load no active process before either reserves | One process is created; one reservation wins |
| Cron versus operator advance | Both read revision r | One transition commits at r+1; loser reloads |
| Poller versus lease replacement | Old poller pauses; new worker acquires lease | Old result cannot commit |
| Composition retry versus late original result | Retry succeeds before original worker resumes | Late original result rejected without state change |
| Two publication workers | Both prepare same or different bytes | Same bytes yield one commit and one no-op; differing bytes yield one commit and one quarantine/conflict |
| Correction versus cache purge | Correction commits while purge starts | Purge affects cache only; manifest identity remains authoritative |
| Old release versus new release | Both attempt transition under compatible or incompatible schema | Only approved release/schema may mutate; old release rejected |
| Cleanup versus public read | Cleanup scans while readers fetch current artifact | Referenced generation remains available |
| Cleanup versus rollback | Rollback marks previous generation current during cleanup | Both current and rollback-safe generations are protected |
| Scheduler tick during quarantine | Scheduler sees overdue target and quarantined process | No replacement process or provider call is started automatically |
Chaos matrix.
| Injection point | Expected safe behavior and invariant | Observable metric and audit event | Recovery | Pass/fail criterion |
|---|---|---|---|---|
| Kill worker after provider acceptance | Durable operation identity survives; no second create | Provider age remains; external_effect=true, reconciliation_required=true event | New worker polls/retrieves same operation | Exactly one provider create |
| Lose network response after successful create | Outcome marked ambiguous, not failed | Ambiguous create result and reconciliation counter | Lookup/reconcile by idempotency or durable request reference | No duplicate create; otherwise quarantine |
| Delay poll beyond lease expiry | Replacement may poll; old worker cannot commit | Lease expiry plus stale rejection | Current lease owner reconciles operation | One committed result |
| Return old provider result after process replacement | Result rejected unless process/operation/target match current state | Stale transition and old-operation event | Archive observation; do not apply | Current process unchanged |
| Make publication directory unwritable | No public pointer changes | Publication failure counter, permission error class | Repair permissions, rerun preparation from validated package | Prior edition remains complete |
| Corrupt temporary package | Checksum validation fails before commit | Artifact mismatch and quarantine event | Rebuild from retained validated inputs | Corrupt bytes never become canonical |
| Serve stale JSON through mock CDN | Synthetic detects old event/revision and excessive age | Cache-age histogram and status mismatch | Revalidate or purge exact key | No workflow retry or republication |
| Run two releases concurrently | Unexpected release cannot mutate or publish | Release observation and stale/schema rejection | Drain old release or roll back new | One writer release only |
| Roll system clock backward | Monotonic-duration calculations remain valid; event wall time anomaly flagged | Clock-skew event; duration does not become negative | Use monotonic clock for leases/durations; authoritative UTC for reporting | No premature lease or target regression |
| Remove one bilingual artifact | Manifest verification fails; pair treated unavailable/inconsistent | Bilingual/artifact mismatch | Restore exact artifact or revert shared pointer | Never serve “healthy” pair |
| Fail ledger write after snapshot update | Reconciler detects snapshot revision without matching committed event | Audit-gap event | Append recovery event referencing snapshot hash | No duplicate stage execution |
| Fail snapshot update after ledger write | Intent remains unmatched and visible | Pending-transition/reconciliation metric | Reapply CAS if still valid or mark intent aborted | No skipped revision or external repeat |
| Restart during publication rename | Public pointer resolves to old or new complete manifest | Publication reconciliation event | Verify pointer and package; finalize ledger | No mixed package |
| Trigger cron and operator action simultaneously | CAS chooses one transition; loser reports conflict | Lock/CAS metrics and two audited trigger events | Loser reloads and takes no external action | Exactly one state change |
| Provider completes after quarantine | Completion is recorded but not automatically consumed into an invalid process | Quarantined-completion event | Explicit reconciliation may reuse or abandon according to policy | No publication from quarantined state |
| CDN purge fails partially | Origin remains correct; edge inconsistency visible | Per-edge mismatch observations | Retry bounded targeted purge; escalate CDN | No republish and no global unbounded purge loop |
Safe-ZIP and package verification. A release package test must:
- extract into a new empty directory;
- reject absolute paths,
..traversal, symlinks, devices, duplicate normalized names, and case-colliding names; - enforce file-count and uncompressed-size ceilings;
- verify an allowlisted inventory and manifest before execution;
- run syntax and schema checks against extracted bytes;
- compare package hashes byte-for-byte with the approved build;
- start a loopback web server with provider networking disabled;
- verify that no runtime-generated secret, cache, log, private source, or credential file is present.
Production synthetic monitoring and incident response
Read-only synthetic contract. Synthetic monitoring must be structurally incapable of becoming a trigger source:
- Synthetic agents receive no scheduler, operator, provider, publication, cache-purge, or database credentials.
- They use only
GET,HEAD, and a special edge-only mutation-gate probe. - Public handlers do not interpret user agents, query strings, headers, or probe paths as workflow triggers.
- Scheduler execution is allowed only through CLI or an authenticated internal channel, never ordinary public HTTP.
- The monitor’s
X-Synthetic-Read-Only: 1header is informational, not an authorization control. - A dedicated route such as
/_assurance/mutation-gatetests host/method policy at the webserver or edge and terminates before application bootstrap. It never calls a real mutation endpoint. - Synthetic state is stored in the monitoring system only to compare successive revisions and event IDs.
- Rate and response-size limits protect origin and CDN resources.
- Synthetic requests use no reader identifiers, cookies, or personal data.
Synthetic suite.
| Check | Procedure and success condition | Failure detected | Evidence and safe action | False-positive control |
|---|---|---|---|---|
| Canonical redirect | Request HTTP, HTTPS alternate, www, and configured aliases; require bounded redirect to exact canonical scheme/host/path | Host drift, redirect loops, insecure canonicalization | Redirect transcript; fix edge rule | Probe from two resolvers before paging |
| Alternate-host mutation rejection | Send an unauthenticated POST to edge-only guard route on alternate host; require 403/405/421 before PHP writer bootstrap | Alternate host can reach mutation plane | Edge decision header; disable route or force redirect | Route must be guaranteed side-effect-free |
| Public status availability | GET bounded public status; require schema-valid response and allowed fields only | Endpoint outage or accidental secret exposure | Schema/privacy validator result | Retry from second region |
| Status freshness | Compare generated_at, event, and revision age with configured TTL | Stale origin/CDN/PHP cache | Headers and identity; purge/revalidate | Compare direct origin control probe |
| Revision monotonicity | Persist last observed revision per process/event; reject unexplained decrease | Snapshot rollback, stale cache, split instance | Observation sequence | Allow only explicit rollback event with new publication generation |
| English/Spanish identity parity | Fetch both statuses/manifests in one window | Split bilingual state | Paired observation | Repeat with cache bypass and origin |
| Artifact availability | HEAD then conditional GET current manifest artifacts | Missing files, wrong route, truncated object | HTTP metadata and byte count | Verify from origin and public edge |
| Edition hashes | Stream and hash artifacts; compare with manifest | Corruption, stale object, wrong artifact | Observed/expected hashes | Two independent downloads |
| Cache headers | Validate ETag, Last-Modified, Cache-Control, Vary, Age, and conditional 304 behavior | Unsafe or ineffective caching | Header report | Evaluate by endpoint class |
| Release consistency | Read bounded X-Service-Version or status field from multiple paths and times | Multiple releases, CLI/web drift where exposed | Release observations | Respect declared canary window |
| Site-instance consistency | Read opaque X-Site-Instance from canonical and alternate observations | Multiple origins or split brain | Instance matrix | Multiple instances may be valid only if explicitly configured and share state |
| Scheduler heartbeat age | Read bounded heartbeat age/status, not internal path or command | Missed cron | Heartbeat observation | Account for schedule and jitter |
| Public versus origin | Compare event, revision, target, release, and generated time | Cache divergence | Pairwise diff | Origin probe is authenticated only to the monitoring plane, read-only |
| Service-worker version | Browser synthetic verifies active worker and cache generation | Old client cache controls page | Browser trace | Test fresh profile and long-lived profile |
| Browser multi-tab | Open old tab, publish fixture only in staging/canary, observe newer status in second tab | Regressive UI or stale tab action | Browser timeline | Production version limited to read-only observation |
RFC 9111 requires cache behavior to preserve HTTP semantics but also allows cached responses to remain reusable according to freshness and validation rules. The synthetic therefore validates both headers and edition identity; a plausible cache header alone is insufficient.
Controlled provider probe. This is optional and separate from the normal synthetic suite. It must use:
- a separate provider project or key with the minimum possible permissions;
- a separate state namespace that cannot reference or write a Daily Brief process;
- an explicit per-call and monthly budget;
- a deterministic, non-sensitive test input;
- no publication, evidence, composition, or scheduler integration;
- a low frequency, such as once per day or after provider-configuration change;
- an immediate circuit breaker after one failure;
- retention settings reviewed against the exact provider mode.
OpenAI documents that some API modes retain application state and that background mode requires temporary stored state for polling, so a controlled probe must be reviewed against the account’s privacy requirements rather than assumed to be retention-free.
A provider probe proves connectivity and authentication only. It does not prove that the production workflow preserves operation identifiers, reconciles completions, validates evidence, or publishes correctly.
Incident severity.
| Severity | Definition | Examples | Response objective |
|---|---|---|---|
| SEV-1 | Active reader harm, wrong edition identity, integrity violation, split publication, unsafe mutation exposure | English/Spanish mismatch, manifest hash mismatch, two canonical instances with divergent editions, invalid artifact publicly committed | Immediate page; stop unsafe writes; restore last known-good complete edition |
| SEV-2 | Publication is overdue or likely to miss deadline; workflow cannot progress or reconcile safely | Scheduler absent near deadline, provider complete but unconsumed, process beyond maximum age | Page promptly; establish current operation and recover without duplicate work |
| SEV-3 | Degraded reliability or rising toil without current major reader impact | Lock contention, repeated leases, cost warning, repeated manual actions | Working-hours response unless rapidly approaching deadline |
| SEV-4 | Test, documentation, or nonproduction defect | Failed deterministic fixture, staging synthetic mismatch | Track in engineering workflow |
Operator action policy.
| Action | Use when | Preconditions | Must not do |
|---|---|---|---|
| Wait | Provider is pending, lease valid, stage within dwell target, next poll scheduled | Operation ID present and status observations progressing | Wait past deadline or lease expiry without alert ownership |
| Poll | Poll eligibility time reached and current operation/revision match | No concurrent poll lease; bounded backoff | Poll in tight loop |
| Reconcile | Create response was ambiguous, provider completed but unconsumed, or publication outcome is uncertain | Stable operation or manifest reference exists | Start replacement work first |
| Advance | Current stage output is complete and transition preconditions pass | Expected revision and lease ownership | Force state past failed validation |
| Retry | Failure is local and idempotent, such as composition from retained evidence | Retry budget available; inputs immutable | Repeat primary research when retained evidence remains valid |
| Quarantine | Ambiguity, invariant violation, repeated leases, hash mismatch, or unsafe release overlap | Audit event records reason and current references | Continue automatic external effects |
| Abandon | Operation is provably unrecoverable, obsolete, and cannot later mutate current state | Explicit operator approval; operation identity retained; process quarantined | Delete evidence or IDs needed for later reconciliation |
| Roll back | New release or publication generation is demonstrably defective and prior version is compatible and complete | Tested rollback bundle and schema compatibility | Roll back application while leaving incompatible workers active |
| Purge cache | Origin is correct and public layers are stale | Exact keys/paths and expected event known | Republish content merely to change cache identity |
| Repair permissions | Storage check proves path ownership/mode problem | Backup/current artifact verified | Recursively broaden permissions |
| Escalate to hosting | Cron, DNS, TLS, filesystem, PHP runtime, or origin routing is outside application control | Doctor results and timestamps collected | Provide credentials or private content in ticket |
| Escalate to provider | Durable operation is stuck, unavailable, or billed incorrectly after local reconciliation | Provider request reference, timestamps, status classes, and redacted trace available | Send prompts, full source material, response body, or credentials |
Incident decision tree.
flowchart TD
A[Alert received] --> B{Reader-visible identity or integrity wrong?}
B -- Yes --> C[Declare SEV-1]
C --> D[Disable unsafe mutations]
D --> E{Prior complete shared manifest available?}
E -- Yes --> F[Atomically restore prior manifest]
E -- No --> G[Quarantine and serve bounded unavailable/stale notice]
F --> H[Verify EN/ES, hashes, hosts, cache]
G --> H
B -- No --> I{Target overdue or deadline at risk?}
I -- Yes --> J[Declare SEV-2]
I -- No --> K[SEV-3 investigation]
J --> L{Durable external operation exists?}
K --> L
L -- Yes --> M{Terminal provider/publication outcome known?}
M -- No --> N[Wait or poll only if eligible]
M -- Yes --> O[Reconcile same operation or manifest]
L -- No --> P{External effect may have occurred?}
P -- Yes or unknown --> Q[Quarantine; investigate ambiguous create]
P -- No --> R{Valid retained evidence exists?}
R -- Yes --> S[Retry downstream stage only]
R -- No --> T[Start bounded research only with approval and budget]
O --> U{Current revision and lease match?}
U -- No --> V[Reject stale action and reload]
U -- Yes --> W[Commit one transition]
W --> X[Run public synthetic verification]
X --> Y{All acceptance probes pass?}
Y -- Yes --> Z[Resolve and schedule review]
Y -- No --> C
First ten minutes.
| Minute | Required action |
|---|---|
| 0–2 | Acknowledge, classify severity, capture current public status, English/Spanish manifests, release, site instances, and cache headers |
| 2–4 | Freeze nonessential deployments and operator mutations; identify authoritative process, revision, lease, and operation |
| 4–6 | Decide whether the problem is workflow, publication integrity, serving/cache, release split, scheduler, or provider lifecycle |
| 6–8 | Perform one bounded action: poll, reconcile, revert shared manifest, purge exact cache key, or quarantine |
| 8–10 | Re-run independent public synthetics; escalate with a redacted evidence bundle if health is not restored |
Operator process report, release proof, rollback, and postmortem
Bounded operator process report. This report is authenticated and richer than public status but still contains no prompts, source text, provider bodies, credentials, private paths, account IDs, reader data, or raw exception strings.
{
"report_schema": 1,
"generated_at": "2026-08-01T11:25:00Z",
"overall_health": "degraded",
"reader_impact": "edition_not_yet_overdue",
"expected_target": "2026-08-01",
"last_published_target": "2026-07-31",
"deadline": {
"model": "fixed_local",
"timezone": "REDACTED_CONFIG_VALUE",
"deadline_local": "CONFIGURED",
"minutes_remaining": 42
},
"process": {
"reference": "p_6C9A1D",
"target_date": "2026-08-01",
"state": "research_reconciling",
"revision": 18,
"age_seconds": 1840,
"stage_age_seconds": 620,
"quarantined": false
},
"lease": {
"status": "valid",
"expires_in_seconds": 73,
"renewal_count": 2
},
"operation": {
"class": "primary_research",
"reference": "op_F3A9",
"identity_present": true,
"provider_state": "completed",
"age_seconds": 1210,
"last_poll_age_seconds": 540,
"next_poll_eligible_in_seconds": 0,
"reconciliation_required": true
},
"evidence": {
"retained_sources": 18,
"retained_candidates": 9,
"selectable_candidates": 5,
"corroborated_candidates": 3,
"represented_regions": 3,
"hard_floor_met": false,
"deficits": ["corroboration", "regional_representation"]
},
"publication": {
"state": "not_prepared",
"current_public_event": "pub_20260731_7B1C",
"english_spanish_parity": true,
"artifact_integrity": "verified"
},
"deployment": {
"web_release": "2026.08.01+8ae73a",
"cli_release": "2026.08.01+8ae73a",
"site_instance_count_observed": 1,
"unexpected_releases": 0
},
"scheduler": {
"heartbeat_age_seconds": 112,
"expected_interval_seconds": 300,
"last_result": "supervisor_tick_completed"
},
"recommended_actions": [
{
"action": "reconcile",
"reason": "provider_completed_not_consumed",
"safe": true,
"expected_revision": 18
}
],
"prohibited_actions": [
"start_new_primary_research",
"force_publish",
"delete_operation_reference"
],
"report_integrity_hash": "sha256:410d…98ac"
}
The public status endpoint should expose only:
generated_at
service_state: healthy | delayed | unavailable | correcting
expected_target
published_target
publication_event_id or short public edition ID
revision
language_parity: true | false
artifact_integrity: verified | unknown
scheduler_freshness_band: current | delayed | unknown
release_channel: current | previous
It should not expose worker IDs, provider names or IDs, attempt internals, detailed evidence sources, private topology, error text, file locations, account information, or trace identifiers.
Release gate.
| Gate | Required proof | Blocking failure |
|---|---|---|
| Syntax validation | PHP lint for every shipped PHP file and configuration parser test | Any syntax or parse failure |
| Schema validation | State, event, public-status, operator-report, and manifest schema compatibility | Missing migration or incompatible reader/writer |
| Deterministic tests | Full no-network state/provider/publication suite | Any invariant failure or network attempt |
| Property tests | Minimum seed count and retained failing seeds rerun | Unresolved minimized counterexample |
| Concurrency tests | Reservation, stale-worker, poll, publication, and dual-release race suite | More than one winner or stale commit |
| Crash tests | Every external-effect and storage boundary | Duplicate external action, mixed publication, unrecoverable ambiguity |
| Clean package | Safe extraction, inventory, checksum, secret scan, byte comparison | Unexpected or modified file |
| HTTP smoke | Loopback canonical routes, redirects, status schema, headers, artifacts | Wrong route, status, cache, or privacy behavior |
| Responsive browser proof | Desktop/mobile viewport, English/Spanish, multi-tab, offline/online, service worker | Identity regression, stale UI represented as current |
| Canonical-host proof | Redirect and mutation-gate tests | Alternate host can mutate or bypass canonical origin |
| Scheduler doctor | CLI can load approved release/config and emit read-only heartbeat doctor result | CLI/web release mismatch or missing runtime dependency |
| Observability validation | Required metrics, event schema, trace/log correlation, cardinality budget | Missing critical telemetry or high-cardinality labels |
| Rollback rehearsal | Restore previous release and prior complete publication manifest in staging | Incompatible schema or unverified artifact |
| Production canary | One instance or bounded traffic with mutation authority carefully controlled | Unexpected state writes, status mismatch, error-budget burn |
| Post-deploy synthetics | Canonical, parity, hashes, release, instance, cache, heartbeat | Any hard invariant failure |
Canary strategy. A web canary may serve read-only traffic first. Only one release may hold workflow mutation authority at a time. Mutation authority should be a lease or configuration generation held by the approved release, not inferred from deployment order. The new release should first prove:
- it reads current state and manifests;
- its public status agrees with the current release;
- its metrics and events have expected schema;
- it rejects stale expected revisions;
- its scheduler doctor is healthy;
- it can process a deterministic isolated canary namespace;
- mutation authority can transfer atomically;
- the prior release is drained before new live work begins.
Rollback strategy. Rollback consists of three independent decisions:
| Plane | Rollback operation |
|---|---|
| Application release | Restore prior approved web/CLI package and verify schema compatibility |
| Workflow authority | Transfer the single mutation lease to the prior release only after new workers are drained |
| Publication | Restore the prior complete bilingual manifest by atomic pointer change; do not rewrite artifacts |
A rollback is complete only when external synthetics see one release, one site identity set, one shared English/Spanish event, correct hashes, fresh bounded status, and a valid scheduler heartbeat.
Release-proof bundle.
release-proof/
release-manifest.json
source-package.sha256
extracted-inventory.json
php-lint-results.json
schema-compatibility.json
deterministic-test-results.json
property-test-seeds.json
concurrency-race-results.json
crash-matrix-results.json
package-safety-results.json
loopback-http-transcript.json
browser-proof/
scheduler-doctor.json
telemetry-schema-validation.json
cardinality-estimate.json
rollback-rehearsal.json
canary-observations.json
post-deploy-synthetics.json
proof-bundle.sha256
approval-signatures.json
Postmortem template.
# Daily Brief Incident Postmortem
## Impact
Affected targets, languages, hosts, reader-visible duration, and edition identity.
## Reader-visible symptoms
What readers actually saw: missing, stale, inconsistent, invalid, or corrected content.
## Detection
First signal, detection time, expected signal, and why earlier controls did or did not fire.
## Timeline
UTC and editorial-local timestamps for scheduler, reservations, provider events,
state transitions, publication events, cache observations, operator actions, and recovery.
## Violated invariant or SLO
Exact invariant, SLI, SLO target, and error-budget consumption.
## Root cause
The specific technical or procedural mechanism that directly produced the incident.
## Contributing conditions
Deployment, topology, permissions, cache, lease, test coverage, provider, and operational factors.
## Why tests passed while production failed
Identify the missing relationship, environment assumption, race, cache layer,
scheduler path, release path, or observation gap.
## Immediate mitigation
Actions taken, why they were safe, and evidence that duplicate work did not occur.
## Permanent correction
Code, infrastructure, test, telemetry, runbook, and editorial-policy changes.
## Regression proof
Deterministic test, race test, crash test, synthetic, or release gate that now catches the defect.
## Data and privacy review
Confirm that diagnosis and escalation did not expose prompts, sources, bodies,
credentials, private paths, account IDs, or reader data.
## Follow-up actions
Owner, deadline, priority, verification method, and closure evidence for every item.
A postmortem is mandatory for every SEV-1, every freshness-budget exhaustion, and any single incident consuming more than 20% of a period’s budget. That 20% policy follows the pattern in Google’s example error-budget policy, adapted here as an explicit owner decision rather than an industry mandate.
Reliability roadmap, research directions, and final production acceptance
Thirty-day foundation.
| Workstream | Deliverable | Acceptance evidence |
|---|---|---|
| Service contract | Editorial deadline model, timezone, expected publication calendar, evidence floors, correction policy | Approved SLO document |
| Identity | Stable release, site-instance, process, operation, event, and publication-manifest identities | Cross-endpoint identity test |
| Public status | Privacy-reviewed bounded status schema | Schema test and field allowlist |
| Core metrics | Scheduler, process, stage, provider, evidence, publication, parity, cache, release | Metric inventory and cardinality report |
| Event ledger | Canonical structured event schema and integrity hash chain | Tamper/reconstruction test |
| Deterministic proof | No-network lifecycle test through interrupted publication and duplicate no-op | CI artifact with zero network attempts |
| Basic synthetics | Canonical redirect, status freshness, parity, artifacts, hashes, release, instance, heartbeat | External observation history |
| Runbook | SEV definitions, action policy, process report, first-ten-minute checklist | Tabletop exercise |
Sixty-day resilience.
| Workstream | Deliverable | Acceptance evidence |
|---|---|---|
| Concurrency | Real-store races for reservations, leases, polling, publication, and releases | Repeatable race suite |
| Crash safety | Injection at every ledger, snapshot, provider, artifact, and pointer boundary | Crash matrix with no duplicate external effect |
| Cache/browser | Origin/CDN/service-worker/multi-tab/offline test harness | Browser and cache transcripts |
| Alerting | Stage-specific alerts, deadline alerts, parity and artifact pages, burn-rate reporting | Alert test and paging drill |
| Recovery | Automated same-operation reconciliation and bounded quarantine | Provider and publication recovery fixtures |
| Release proof | Clean package, loopback HTTP, scheduler doctor, observability gate, rollback rehearsal | Signed proof bundle |
| Baseline | Four weeks of stage, recovery, cache, retry, and evidence distributions | Threshold calibration report |
Ninety-day operationalization.
| Workstream | Deliverable | Acceptance evidence |
|---|---|---|
| SLO governance | Freshness, recovery, status, evidence, parity, and operator-safety scorecards | Monthly review and budget policy |
| Production chaos | Approved low-risk cache, scheduler, old-worker, and release-split exercises | Game-day reports |
| Provider assurance | Optional isolated, hard-budget probe plus reconciliation drill | Cost/privacy approval and probe history |
| Editorial quality | Human sampling and correction-parity review | Audit sample and correction metrics |
| Multi-region synthetics | Independent origin/CDN observations | Regional consistency dashboard |
| Postmortem discipline | Completed reviews and tracked corrective actions | Closure evidence |
| Release policy | Freeze or restrict risky changes when budget is exhausted | Enforced deployment policy |
Five concrete research and policy directions.
| Direction | Research question and recommended policy |
|---|---|
| Publication-manifest formalization | Determine the minimum manifest that can prove target, revision, bilingual identity, evidence-policy outcome, and artifact integrity across filesystem, database, CDN, and browser layers. Adopt the manifest as the sole public commit object. |
| Storage atomicity characterization | Benchmark and fault-test the actual filesystem/database/object-store semantics, especially rename across mounts, fsync behavior, transaction isolation, lock expiry, and recovery after host restart. Select the commit protocol from measured guarantees rather than assumptions. |
| Provider reconciliation study | Verify the exact provider API’s request identity, retrieval window, terminal states, rate limits, billing semantics, and ambiguous-response behavior. Require reconciliation evidence before any replacement request. |
| Editorial correctness measurement | Develop a labeled audit sample that compares automated evidence scores with human findings. Recalibrate selectable, corroboration, regional, and factual-correction thresholds from observed false positives and false negatives. |
| Cache and deployment topology census | Map every host, DNS path, origin, PHP runtime, CDN behavior, service worker, scheduler binary, shared state location, and release path. Make unexpected topology observable and release-blocking. |
Unresolved evidence and conflicting design pressures.
| Tension | Implication |
|---|---|
| Full OpenTelemetry versus constrained hosting | OTel offers standardized correlation, but structured JSON plus a small metric exporter may be more reliable on limited hosting. Start with the simpler option if the collector would itself become an unmaintainable dependency. |
| Very strict SLO versus daily sample size | A 99% daily deadline SLO can be exhausted by one miss in a 90-edition window. Preserve the strict reader promise but use a proportionate change policy and direct incident controls. |
| Fast automatic recovery versus duplicate-work safety | Aggressive retries improve apparent progress but can duplicate provider cost and publication effects. Reconciliation must take precedence over replacement. |
| Public transparency versus privacy and attack surface | Status must reveal enough to prove freshness and parity but not provider details, paths, prompts, sources, topology, or operator information. |
| Atomicity across heterogeneous stores | A database state change and filesystem/CDN publication cannot generally be assumed to share one atomic transaction. Use immutable artifacts, a final canonical pointer, explicit intents, and reconciliation. |
| Automated evidence checks versus factual correctness | Counts and validators prove policy compliance, not truth. Human audit sampling and bilingual correction governance remain necessary. |
Final production acceptance criteria. The Daily Brief is accepted as production-ready only when all conditions below have reproducible evidence:
| Domain | Acceptance condition |
|---|---|
| Process identity | One logical process exists for each target; target cannot mutate |
| State sequence | Every committed revision advances by exactly one and is reconstructable from events |
| Coordination | Deterministic races prove exactly one reservation and one transition writer |
| Stale safety | Old workers, old releases, expired leases, and old provider results cannot commit |
| External operations | Every provider operation has durable identity before polling; ambiguous outcomes reconcile before replacement |
| Evidence | Valid evidence survives downstream failures; supplemental work repairs deficits rather than repeating full research |
| Composition retry | Composition may retry from the same retained evidence without provider work |
| Publication | Immutable bilingual artifacts are verified before one atomic canonical-pointer commit |
| Integrity | Public bytes match manifest hashes from at least two independent observation points |
| Bilingual parity | English and Spanish always share target, publication event, revision, and correction generation |
| Idempotency | Duplicate publication is a no-op with unchanged bytes, event identity, pointer, and provider-call count |
| Scheduler | Heartbeat is observable, current, and tied to the approved CLI release |
| Deployment | Canonical web and scheduler releases agree; unexpected releases cannot mutate |
| Instance topology | Every serving instance is expected, identifiable, and state-consistent |
| Cache | Origin, CDN, browser, and service-worker identities converge within defined TTL; stale caches never trigger workflow retry |
| Recovery | Crash and chaos matrices meet recovery SLO without duplicate external work |
| Privacy | Public status, metrics, logs, events, traces, alerts, and support bundles pass field-allowlist and secret-leak tests |
| Synthetics | Production probes are read-only by construction and cannot invoke scheduler, provider, operator, or publication actions |
| Incident readiness | On-call personnel complete a tabletop using the bounded process report and decision tree |
| Release readiness | Every release has a complete, checksum-protected proof bundle and successful rollback rehearsal |
| Editorial governance | Deadline, evidence floors, exception policy, bilingual correction policy, and human audit process are approved |
One-page operator checklist.
- [ ] Confirm the expected target date, editorial timezone, deadline, and grace period.
- [ ] Capture canonical English and Spanish publication IDs, revisions, hashes, releases, instances, and cache ages.
- [ ] Determine whether the issue is reader integrity, freshness, workflow progress, scheduler, provider reconciliation, publication, cache, or release topology.
- [ ] Freeze nonessential deployments and mutating operator actions during SEV-1 or SEV-2 response.
- [ ] Read the bounded process report; record process reference, immutable target, current revision, state, stage age, lease, and operation reference.
- [ ] Never start a new provider operation while an existing or ambiguous operation may exist.
- [ ] Poll only when eligible; otherwise wait within the stage/deadline bound.
- [ ] Reconcile completed or ambiguous provider work before retrying.
- [ ] Reuse retained evidence for composition, validation, and publication retries.
- [ ] Reject or ignore every worker result whose process, target, operation, lease, or expected revision is stale.
- [ ] Quarantine on hash mismatch, bilingual divergence, repeated lease expiry, unknown external outcome, or concurrent mutating releases.
- [ ] For stale public data, compare origin and cache identities; purge or revalidate the exact cache object rather than republishing.
- [ ] For publication failure, verify the manifest and both artifacts before committing or restoring a canonical pointer.
- [ ] Never repair only one language; restore or commit a shared bilingual generation.
- [ ] After any action, run external checks for canonical host, target, revision, event, parity, hashes, release, instance, cache age, and heartbeat.
- [ ] Record the operator action with expected revision, result, reason, and integrity hash.
- [ ] Escalate with opaque operation references, timestamps, statuses, and error classes only—never prompts, raw sources, response bodies, credentials, private paths, account identifiers, or reader data.
- [ ] Resolve the incident only after reader-facing synthetics pass and recovery evidence is attached.
- [ ] Open a postmortem for SEV-1, freshness-budget exhaustion, unsafe duplicate-work risk, or a major detection gap.
- [ ] Convert the discovered failure into a deterministic, race, crash, browser, cache, synthetic, or release-gate regression test.