# Yunke App — deferred caller and scheduled placement

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
This is the App/Web candidate route, a documented deviation from the PDF's official
standing-task/import/callback route. It is default off and has not been live-accepted.

## What it does

Connects the existing `PlaceAiVoiceCall` guards to the
[single-task submitter](/docs/modules_handbook/shared/voice-agent/yunke-app-submit.md)
and durable result ledger. The existing four-argument `ConversationalCaller` signature
is unchanged. Accepted or uncertain task creation keeps the call PENDING, without
inventing a per-call ID, a missed call, a cost or a follow-up.

The resolver selects `YunkeConversationalCaller` only when `YUNKE_APP_WRITE_ENABLED`
is explicitly enabled. Configuration still requires an existing App token, exact
company/user and a nonempty exact-number allowlist. No runtime flag or credential was
changed during development. In local mode without `VOICE_REAL_IN_LOCAL`, the resolver
uses the existing log-only caller; the real adapter also refuses a direct local bypass.

There is no new public write endpoint, CLI, login or automatic token refresh. A future
live enablement requires the separate owner/vendor acceptance steps in the
[PDF progress ledger](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md).

## How it works

### Explicit profile mode and shared guards

An App profile has provider=yunke, `provider_settings.mode=app_single_task`, a nonempty
`dial_prefixes` market, positive `daily_cap` and an explicit same-day `call_window` (any hours since 2026-11-10).
The new [paused provisioning command](/docs/modules_handbook/shared/voice-agent/yunke-profiles.md)
prepares those facts without submitting a task; its configuration is read-only in the UI.
It does not require a standing task_id: each accepted
attempt receives a new parent ID, stored only on its binding. App `agent_id` stays null.
Legacy static-task profiles are never silently migrated to the real App caller.

Retell readiness, default caller ID and content hashing remain unchanged. Placement
keeps the shared blocked-number/contact policy, market, calling-window and atomic
profile-cap guards. The profile cap is not a verified shared-SIM inventory limit.
Funnel deferral now uses the **selected profile's** window even when global Retell quiet
hours are off. The App adapter also checks its window before a new submission, so an
accidental quiet-hours bypass cannot create a phone task at night.

### One scheduled task and an opaque local receipt

The caller requires the exact local call UUID from placement metadata, the matching
Yunke profile and normalized recipient. Phones/times never discover or associate calls.
The existing committed-claim sender receives one scheduled descriptor:

- One recipient, unchanged E.164; task name is `petaV3-` plus a stable 24-hex-character
  SHA-256 fingerprint of the call UUID (31 characters total). Reusing numeric row IDs
  in another database no longer reuses the name. Neither the original UUID nor the
  phone/company/user is included in it. Existing claimed bindings are returned before
  a descriptor is rebuilt; changing the naming format never resends old work.
- Start epoch is now, end epoch is the selected window's end **on the same local day**.
- The same-version observed all-week scheduledDays list is used inside that bounded
  date range; there is no assumed vendor weekday-number conversion.
- One selected-window period and raw redialCount=0. That raw value is not proof that
  every vendor retry path is disabled.

The committed claim now freezes this schedule and client claim/first-acknowledgement
timestamps in `meta.yunke_submission`. The default-off [watch](/docs/modules_handbook/shared/voice-agent/yunke-watch.md)
uses those facts, rather than later profile settings, when reviewing queued calls.

The caller does not push the profile's Retell prompt, voice or dynamic variables as
unverified cloud overrides. Explicit optional [scenario instructions](/docs/modules_handbook/shared/voice-agent/yunke-scenarios.md)
use a bounded subset of frozen funnel variables in the recipient's `otherInfo` customer
context. The App's ordinary session builder reads that directly from the matching task;
cloud echo, selected-mode support and spoken behavior still need controlled live evidence.
Cloud prompt/knowledge/opening configuration and its approval
remain Phase 0 work. There is no standing-task append or direct mobile UI automation.

For CREATED or CREATE_UNKNOWN, `call()` returns `yk_pending_` + the local UUID. This is
an **opaque local receipt**, not a vendor call ID. `AiVoiceCallRepository::recordPlaced()`
verifies it against the binding's UUID, committed request hash and claimed state and
returns the existing call unchanged. It never stores the receipt in provider_call_id.
A late null result also cannot turn a verified claimed attempt into not_placed. A
result that raced placement remains settled with its real call ID. Forged receipts fail.

A response-persistence error after a verified claim remains pending with a safe warning;
errors before a claim still propagate. A clear rejection becomes a refusal, including
an explicit non-allowlisted number. Neither path fabricates a no-answer result.
Received rejection/uncertainty warnings include only the internal binding ID, safe reason,
actual HTTP status and a bounded numeric business code from the submitter. Vendor prose,
response data, headers and credentials are not logged; see the
[submission diagnostics](/docs/modules_handbook/shared/voice-agent/yunke-app-submit.md).
`getCall()` makes no request; results use the separate disabled Web collector, never Retell.

### The queue lane a funnel send takes

Every funnel dispatcher builds the job with `SendFunnelAiCall::forRule()`. A Yunke App
campaign's send rides its own lane (`YUNKE_FUNNEL_QUEUE` on `redis-ai`) when one is named —
modelled on, but separate from, AI 2 Rounds' round-1 lane; unset, the caller's lane stands. The claim below is
committed before the send, so the job must only run where Yunke is reachable. See
[yunke-funnel-loop.md](/docs/modules_handbook/shared/voice-agent/yunke-funnel-loop.md).

### Job recovery without another task

Only the initial App funnel dispatch stamps `meta.yunke_funnel_send_id` on its local
call before submission. While holding the existing send lock, a retried QUEUED job
first looks for that exact send/lead/provider intent. A claimed call is recovered even
if the profile since changed provider; no new task or fallback Retell call is made.
An interrupted unclaimed call is reported as `yunke_dispatch_unconfirmed` for review,
without declaring a customer miss or automatically submitting a replacement.

Callbacks and business redials do not inherit this initial-dispatch marker. Redials
retain their own root/attempt dedupe. Queue retry is not a new business attempt.
Stopping a local split is still not cancellation of a task already accepted by the phone.

## Reference usage

`YunkeAppCallerTest::test_placement_schedules_one_bounded_task_and_web_results_supply_the_real_call_id`
runs the real placement/caller/submitter/writers against the guarded test database,
with fake HTTP. It verifies null parent-stage agent/call IDs, the bounded schedule,
one request on UUID replay, then fake Web child/action binding and settlement. A late
placement receipt preserves the completed row and its actual per-call ID. No recording
is downloaded and queues/notifications are fake.

Other tests cover disabled/incomplete/legacy profiles, market/cap/blocking/quiet hours,
uncertain transport, failed response persistence, auth rejection, forged receipts, local
log-only mode, selected-window defer and recovery of a crashed initial funnel dispatch.
These tests are engineering evidence, not a second live S2 test or a customer pilot.

## Related files

- `src/Common/VoiceAgent/YunkeConversationalCaller.php`, `ConversationalCallerResolver.php`, `ConversationalCaller.php` — adapter selection and opaque receipt contract.
- `src/VoiceAgent/AiCallProfile.php`, `AiVoiceCall.php` — explicit mode, readiness and refusal labels.
- `src/VoiceAgent/Services/YunkeAppTaskSubmit.php` — configured scope and committed one-request transport.
- `src/VoiceAgent/Repositories/AiVoiceCallRepository.php` — receipt verification and pending/result preservation.
- `app/Actions/PlaceAiVoiceCall.php`, `app/Jobs/Automation/SendFunnelAiCall.php`, `src/Event/FunnelAutomationSend.php` — existing guards, window defer and durable intent recovery.
- `tests/Feature/VoiceAgent/YunkeAppCallerTest.php`, `YunkeAppTaskSubmitTest.php`, `AiCallSplitTest.php` — fake lifecycle and queue-recovery regressions.
