This is the canonical guide for Chimeway's iPhone-first mobile delivery path. It is deliberately literal: one bounded production path is now physical_support_promoted. A green package, Git revision, Hex artifact, or CI run establishes provenance only; physical-device behavior comes only from the completion-bound promoted record.
Start with your job
- Integrate mobile push — host integrator: prepare the host-owned prerequisites and wiring.
- Explain an outcome — operator/on-call: distinguish the durable facts recorded by Chimeway.
- Review the security boundary — security reviewer: confirm which party owns each trust decision.
- Run or promote proof — maintainer: use the Threshold-A contract today and the signed-device process only when external gates are ready.
Readiness and roles
Chimeway is embedded in the host application. The host integrator owns tenant eligibility and application wiring; the operator explains a recorded outcome; the security reviewer checks the boundary; and the maintainer runs release and proof commands. Begin with the Installation Guide and the Golden Path; this guide does not repeat their procedures.
Ownership boundaries
The host owns recipients, tenancy, authentication, authorization, URL generation, token custody, APNs credentials, and the decision to activate an intent. Chimeway owns its durable event -> notification -> delivery -> attempt lifecycle and explainable trace. CrossWake owns native permission observation, authenticated registration authority, offline protected-open handling, and one-time protected activation. Apple/APNs accepts or rejects a provider request.
Provider acceptance is provider handoff only. It does not prove device receipt or display, protected activation, inbox seen/read, or engagement.
Compatible installation and upgrade
Install and configure Chimeway using the Installation Guide. New installations use the isolated chimeway schema; an existing public-schema installation follows the explicit compatibility steps in the Storage Prefix Upgrade Guide. Do not silently move host data or infer a tenant from a device.
Tenant, APNs, and host wiring
Keep tenant resolution, recipient eligibility, APNs configuration, and host registration/activation authority in the host. Wire async dispatch through the Oban integration recipe when the host uses Oban. Use the custom adapter recipe for adapter seams and the Golden Path for notifier and trace setup.
Provider acceptance is provider handoff only. It does not prove device receipt or display, protected activation, inbox seen/read, or engagement.
Outcome vocabulary
Use these facts without collapsing them: a logical delivery is Chimeway's durable delivery decision; a target is one eligible destination; an attempt is one adapter attempt; provider acceptance is APNs handoff; visible presentation is the separate alert observation; a protected open is CrossWake's authorized one-time activation; inbox seen/read are separate inbox lifecycle facts; and engagement is not inferred by Chimeway.
For a durable explanation, follow Tracing a notification. Provider acceptance is provider handoff only. It does not prove device receipt or display, protected activation, inbox seen/read, or engagement.
Offline protected opens
An offline protected open is queued by CrossWake and re-authorized after reconnect. It remains route-scoped and server-authoritative: tenant, binding revision, expiry, session, manifest, and RouteGate authorization are checked again before one-time consumption. It is not generic background sync, and provider acceptance is provider handoff only—not proof of receipt, display, protected activation, inbox seen/read, or engagement.
Proof ladder
Threshold A — release_ready_physical_pending. This credential-free release gate validates schemas, fixtures, source-bound CrossWake proof, and package integrity. Run:
mix ci.verify_gates
mix verify.alpha_twin
mix verify.physical_proof_contract
mix chimeway.mobile_physical_proof --preflight --json
Threshold A alone remains physical evidence pending. It is not physical behavior evidence.
Threshold B — physical_support_promoted. After Apple signing/provisioning, APNs sandbox, the selected iPhone, host authority, and the CrossWake physical-device reconciliation checks are ready, run the signed-device process. The runner asks exactly: “Did the expected Chimeway alert appear on the selected iPhone?” Choose Observed, Did not appear, or Cannot verify. That observation confirms visible presentation only; it does not establish APNs acceptance, protected activation, inbox state, or engagement. A promotion requires an explicit Observed answer and an append-only validated bundle.
The retained 2026-09-12 proof is physical_support_promoted for opaque run cw-physical-57aa04f3f7f2c1a81d9d2c93. It binds immutable Chimeway artifact 1af6079bed2ec25c95768f0122e0fcd2373636de1999a47e2196409b629229b5 to CrossWake contract v1 at 3165ab6938fa673f8a289c27699658bb78650ef3; the source-owned evidence and marker digests are e63ae014bc57c9fab81b8a892ed04e48b197df151e8ac2073daa35f0f3992d6a and 153eed13526824922a0b804ad453123f484b96556cfb91390b5c22c3eca7c19b. Bundle digest e84ba08c151af2f227f2e0a9e550289f576c8004f3f9b65c13b57ba17e3863fc closes passed delivery, provider-handoff, explanation, permission, registration, protected-activation, and separately observed visible-presentation outcomes. Revalidate it with:
mix chimeway.mobile_physical_proof --verify-promoted --json
This is evidence for that recorded iPhone-first path only. APNs acceptance remains provider handoff, not proof of receipt or display; visible presentation and protected activation are separate facts. The proof makes no inbox seen/read or engagement claim.
Troubleshooting and operator actions
A provider attempt was accepted but no alert was reported
What happened: Chimeway has a provider-acceptance attempt but no visible-presentation fact.
Why it matters: Provider acceptance is provider handoff only. It does not prove device receipt or display, protected activation, inbox seen/read, or engagement.
How to fix: Inspect the Chimeway trace, then have the host and CrossWake owners check authorization, registration, selected-device state, and the bounded visible-alert attestation. Do not backfill or infer Observed.
A protected open is unavailable after reconnect
What happened: CrossWake did not authorize one-time activation.
Why it matters: Reauthorization prevents stale, replayed, expired, revoked, logged-out, or tenant-switched intents from activating a fallback route.
How to fix: Resolve the host session, tenant, binding revision, and route authorization, then create a fresh intent. Use a new proof run; never overwrite retained evidence.
The release gate is green before physical promotion
What happened: Threshold A completed.
Why it matters: Package/CI provenance is not APNs receipt, display, or protected-open evidence.
How to fix: Keep public support wording at physical evidence pending until the signed-device Threshold-B bundle is validated and promoted. Once promoted, keep the claim bounded to the recorded path and revalidate the completion-bound snapshot.
Non-goals
This guide does not deliver Android or FCM transport, generic offline/background sync, broad device support, device management, a general attestation platform, push analytics, raw-token storage, screenshots/video, rich-media campaigns, or arbitrary notification actions. Chimeway does not claim that APNs acceptance establishes receipt, display, protected activation, inbox read/seen, or engagement.