# Push Notification API × Agent：通知送信を業務実行と誤認しないための設計

CURRENT_STATUS: CURRENT
OBSERVATION: SPEC_ONLY
FRESHNESS: CURRENT
PAGE_TYPE: reference
CANONICAL_URL: /tools/ea-228-push-notification-api-agent
CLAIM_IDS: none
EVIDENCE_IDS: EVD-EA-228-URL-3ACC68895F3E, EVD-EA-228-URL-E46D4CC93A09, EVD-EA-228-URL-BE91BDFB2039, EVD-EA-228-URL-3E4860C8E551, EVD-EA-228-URL-2AA16940C9B8, EVD-EA-228-URL-8160BCBB9A53, EA-228-CURRENT-APPROVAL, EA-228-CURRENT-BODY-READBACK
UNKNOWN_IDS: EA-228-UNKNOWN-01
OPS_IDS: none

## Summary
Push Notification APIの送信成功は、利用者への表示・閲覧・承認・業務完了の証明ではありません。Agentから通知を送る場合は、通知をauthoritative stateへの案内として設計し、recipient、event ID、TTL、priority、collapse、rate、sensitivityを制御します。重複・順序逆転・遅延・非表示・throttlingをfailure envelopeへ含め、重要な処理はserver側正本をreadbackして確定します。

## Current judgment
Push Notification APIの送信成功は、利用者への表示・閲覧・承認・業務完了の証明ではありません。Agentから通知を送る場合は、通知をauthoritative stateへの案内として設計し、recipient、event ID、TTL、priority、collapse、rate、sensitivityを制御します。重複・順序逆転・遅延・非表示・throttlingをfailure envelopeへ含め、重要な処理はserver側正本をreadbackして確定します。

## Scope
Push Notification API × Agent：通知送信を業務実行と誤認しないための設計

## Confirmed

## UNKNOWN
- EA-228-UNKNOWN-01: 対象アプリのOS/SDK version、FCM/APNs direct利用範囲、tenant quota、token lifecycle、topic管理、通知許可率、delivery/open計測、quiet-hours policy、critical/privileged notification entitlement、idempotency実装、retry policy、PII classification、incident時kill switch、法的通知要件は未確認です。

## Evidence
- EVD-EA-228-URL-3ACC68895F3E (RESEARCH): Firebase Cloud Messaging, Message types: — https://firebase.google.com/docs/cloud-messaging/customize-messages/set-message-type
- EVD-EA-228-URL-E46D4CC93A09 (RESEARCH): Firebase Cloud Messaging, Collapsible messages: — https://firebase.google.com/docs/cloud-messaging/customize-messages/collapsible-message-types
- EVD-EA-228-URL-BE91BDFB2039 (RESEARCH): Firebase Cloud Messaging, Android message priority: — https://firebase.google.com/docs/cloud-messaging/android-message-priority
- EVD-EA-228-URL-3E4860C8E551 (RESEARCH): Firebase Cloud Messaging, Customize a message across platforms: — https://firebase.google.com/docs/cloud-messaging/customize-messages/cross-platform
- EVD-EA-228-URL-2AA16940C9B8 (RESEARCH): Apple Developer, Sending notification requests to APNs: — https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns
- EVD-EA-228-URL-8160BCBB9A53 (RESEARCH): Apple Developer, Troubleshooting push notifications: — https://developer.apple.com/documentation/usernotifications/troubleshooting-push-notifications
- EA-228-CURRENT-APPROVAL (RESEARCH): 現行本文の監査・revision対応
- EA-228-CURRENT-BODY-READBACK (IMPL): 現行本文の収録照合

## Failure / limits
provider request timeout後の盲目的retryによる重複通知
## Failure / limits
token失効・誤token・誤topic・誤tenantによる誤配信または未達
## Failure / limits
notification/data messageの取り違え
## Failure / limits
foreground/background差による処理漏れ
## Failure / limits
TTL切れ、offline、OS制御、Doze、Focus/通知許可、battery policyによる遅延・非表示
## Failure / limits
collapseによる中間イベント消失、順序逆転
## Failure / limits
high priorityのdeprioritization/proxy化
## Failure / limits
silent push throttling
## Failure / limits
payloadへの機微情報混入
## Failure / limits
send responseを閲覧・承認・業務完了と誤認
## Failure / limits
retry storm、rate limit、通知疲労、spam判定
## Failure / limits
notification serviceやSDKにはdelivery metrics、priority、TTL、collapse、platform-specific overrideなど豊富な制御があります。しかし、これらは端末状態・OS policy・利用者設定を越えて「必ず即時に見える」保証へは変換できません。逆に、すべてのpushを低信頼として捨てる必要もありません。目的が再同期の促進や一般的なユーザー通知であれば有効ですが、業務正本と通知チャネルの責任を分離する必要があります。
## Practice
FCMはtransport encryptionを提供しますが、data payload自体をend-to-end encryptedとは扱いません。機微情報を通知本文やdataへ直接埋め込まず、必要ならopaque event IDを送り、認証済みclientがserverから権限付きで詳細を取得します。device/registration tokenはrouting credentialとして扱い、ログ・分析基盤・LLM promptへ無制限に露出させません。

Agentには最小権限のsend capabilityを与え、対象tenant/app/topic/user segment、message class、priority、TTL、時間帯、rate、sensitive-content policyをpolicy layerで制限します。大量送信、全体topic、critical alert相当、marketing用途、法的通知等は別approval boundaryにします。
## 主要claim
AI/AgentからPush Notification APIを呼べることは、利用者への確実な通知、閲覧、業務完了を意味しません。送信要求の受付、push serviceでの処理、端末への配信、OSによる表示、利用者の閲覧・操作、業務側の状態更新を別イベントとして扱い、重要な業務ではpushを唯一の正本・唯一の承認経路・唯一の完了証跡にしません。

Firebase Cloud Messaging（FCM）はnotification messageとdata messageを区別し、background時のnotification messageはSDKが表示を扱う一方、data messageはclient appが処理します。notification+dataの混在もforeground/backgroundで挙動が異なります。したがってAgentがpayloadを生成する場合、単に本文を作るのではなく、message type、app state、platform override、TTL、priority、collapse semanticsを契約として固定する必要があります。

## 配信保証と順序の境界
FCMはメッセージ順序を保証しません。collapsible messageは未配信の古いメッセージを新しいものが置き換え得ます。Androidでは同時に保持できるcollapse key数にも制約があります。重要な状態遷移をpushの到着順に依存させず、通知は「正本を取りに行く契機」として扱い、clientはversion/event IDを使ってserver stateをreadbackします。

APNsもprovider requestをHTTP/2で受け付けますが、端末表示までのexactly-once保証として扱うべきではありません。Appleはdevelopmentとproduction endpointを分離しており、接続stream数を固定値と仮定しないよう求めています。connection terminationやerror responseを考慮し、request acceptanceとuser-visible deliveryを分離します。

## priority・background executionの誤解
FCMのAndroid high priorityは、時間依存かつuser-visibleな通知向けです。高優先度を指定しただけで即時実行が保証されるわけではなく、利用状況によってdeprioritizeまたはGoogle Play servicesによるproxy表示が起こり得ます。通知後に長いnetwork処理を前提にせず、追加同期はWorkManager等へ分離します。

Apple側でもsilent/background notificationは無制限の実行トリガではありません。Appleのtroubleshooting guidanceは短時間の過剰送信やsilent notificationのthrottling、power budgetの影響を挙げています。Agent orchestrationのjob schedulerとしてpushを利用し、未達時に無制限再送する設計は避けます。

## security・privacy
FCMはtransport encryptionを提供しますが、data payload自体をend-to-end encryptedとは扱いません。機微情報を通知本文やdataへ直接埋め込まず、必要ならopaque event IDを送り、認証済みclientがserverから権限付きで詳細を取得します。device/registration tokenはrouting credentialとして扱い、ログ・分析基盤・LLM promptへ無制限に露出させません。

Agentには最小権限のsend capabilityを与え、対象tenant/app/topic/user segment、message class、priority、TTL、時間帯、rate、sensitive-content policyをpolicy layerで制限します。大量送信、全体topic、critical alert相当、marketing用途、法的通知等は別approval boundaryにします。

## failure envelope
- provider request timeout後の盲目的retryによる重複通知
- token失効・誤token・誤topic・誤tenantによる誤配信または未達
- notification/data messageの取り違え
- foreground/background差による処理漏れ
- TTL切れ、offline、OS制御、Doze、Focus/通知許可、battery policyによる遅延・非表示
- collapseによる中間イベント消失、順序逆転
- high priorityのdeprioritization/proxy化
- silent push throttling
- payloadへの機微情報混入
- send responseを閲覧・承認・業務完了と誤認
- retry storm、rate limit、通知疲労、spam判定

## control / implementation implication
1. Agent出力は直接provider APIへ渡さず、typed notification requestへ正規化します。recipient selector、message class、event ID、source state version、TTL、priority、collapse key、deep link、sensitivity、approval classを検証します。
2. idempotency keyまたは業務event IDをserver側で保持し、ambiguous timeout時は送信履歴をreadbackしてから再送します。providerがend-to-end idempotencyを保証すると仮定しません。
3. clientはpush payloadを正本にせず、event IDからauthoritative stateを再取得します。古いversionや重複eventを拒否できるようにします。
4. delivery/open analyticsは補助観測です。provider受付、端末到達、表示、open、業務完了を別metricにします。
5. kill switch、per-tenant rate limit、quiet hours、segment size cap、dry-run/test projectを用意します。production credentialとtest credentialを分離します。

## counterevidence / limitations
notification serviceやSDKにはdelivery metrics、priority、TTL、collapse、platform-specific overrideなど豊富な制御があります。しかし、これらは端末状態・OS policy・利用者設定を越えて「必ず即時に見える」保証へは変換できません。逆に、すべてのpushを低信頼として捨てる必要もありません。目的が再同期の促進や一般的なユーザー通知であれば有効ですが、業務正本と通知チャネルの責任を分離する必要があります。

## 適用境界
本項はFCM/APNs等をAgentから利用する際のprovider-neutral運用設計です。Android/iOS/Webではpayload field、priority、TTL、permission、background execution、analyticsが異なります。critical alerts、communication notifications、location push等の特権・entitlementを要する機能は一般pushと同一視しません。tenant固有quota、契約、region、SDK version、OS version、app実装は個別確認が必要です。

## SAFE_WORDING
Push Notification APIの送信成功は、利用者への表示・閲覧・承認・業務完了の証明ではありません。Agentから通知を送る場合は、通知をauthoritative stateへの案内として設計し、recipient、event ID、TTL、priority、collapse、rate、sensitivityを制御します。重複・順序逆転・遅延・非表示・throttlingをfailure envelopeへ含め、重要な処理はserver側正本をreadbackして確定します。

## OPEN_UNKNOWN
対象アプリのOS/SDK version、FCM/APNs direct利用範囲、tenant quota、token lifecycle、topic管理、通知許可率、delivery/open計測、quiet-hours policy、critical/privileged notification entitlement、idempotency実装、retry policy、PII classification、incident時kill switch、法的通知要件は未確認です。

## source / provenance
- Firebase Cloud Messaging, Message types: https://firebase.google.com/docs/cloud-messaging/customize-messages/set-message-type (accessed 2026-10-19)
- Firebase Cloud Messaging, Collapsible messages: https://firebase.google.com/docs/cloud-messaging/customize-messages/collapsible-message-types (accessed 2026-10-19)
- Firebase Cloud Messaging, Android message priority: https://firebase.google.com/docs/cloud-messaging/android-message-priority (accessed 2026-10-19)
- Firebase Cloud Messaging, Customize a message across platforms: https://firebase.google.com/docs/cloud-messaging/customize-messages/cross-platform (accessed 2026-10-19)
- Apple Developer, Sending notification requests to APNs: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns (accessed 2026-10-19)
- Apple Developer, Troubleshooting push notifications: https://developer.apple.com/documentation/usernotifications/troubleshooting-push-notifications (accessed 2026-10-19)

NEXT: /agent/start.json
STOP: This is a knowledge projection, not an execution order.