# Yunke App — guarded single-task submission seam

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
This is an internal default-off transport, not an enabled caller or live acceptance.

## What it does

`YunkeAppTaskSubmit::submit($bindingId, $descriptor)` can submit one unchanged
`YunkeAppTaskAdapter` descriptor for an existing single-call ledger. It uses an explicitly
provisioned existing App token and exact company/user; it never logs in or refreshes a
phone session. No live credentials were added or real requests performed during development.

`YUNKE_APP_WRITE_ENABLED=false` disables the method before database or HTTP work.
An enabled transport additionally requires `YUNKE_APP_WRITE_TOKEN`,
`YUNKE_APP_WRITE_COMPANY_CODE`, `YUNKE_APP_WRITE_USER_ID` and an exact E.164 allowlist
in `YUNKE_APP_WRITE_ALLOWED_NUMBERS`. An empty allowlist permits no sends unless the console's
[market mode](/docs/modules_handbook/shared/voice-agent/yunke-console.md) is on, which checks the
call's own profile market instead. The token
is used only in request headers, never stored in the binding or returned in an outcome.
The existing Inspector redaction covers the App business host.

The separate default-off [App caller](/docs/modules_handbook/shared/voice-agent/yunke-app-caller.md)
now connects this service to the resolver and existing placement/funnel guards. It requires
explicit App profile mode, market, cap and window. There is no task-submission CLI or public
write endpoint. A separate default-off [watch](/docs/modules_handbook/shared/voice-agent/yunke-watch.md)
only collects existing results. Do not invoke this internal method on arbitrary leads instead
of going through shared placement guards. Runtime Yunke profiles remain unavailable while off.

## How it works

1. Refuse missing credentials, a different company/user or a recipient outside the allowlist,
   or outside the profile's market in market mode, without claiming a task. A caller's existing database transaction is rejected: the claim
   must really commit before network I/O, not merely release a nested savepoint.
2. `claimCreate()` verifies the entire pure descriptor, fixed URL/method, exact local phone,
   company/user, local call UUID/provider and pending state. It changes RESERVED to
   CREATE_UNKNOWN in its own committed transaction. Only the winner may send.
3. Make one HTTPS POST to the fixed APK-derived App save URL. TLS verification is enabled,
   redirects are disabled and timeouts are bounded. There is no login, automatic retry,
   endpoint discovery, Cookie fallback or bulk/append transport.
4. The existing response parser/repository stores a literal accepted parent task ID or a
   clear rejection. A missing ID, malformed/contradictory response, transport failure or server
   failure stays CREATE_UNKNOWN. Redirects and throttled responses are also held unknown.
   Rejected authentication has an explicit safe `session_expired`/`auth_failed` reason.
   Received outcomes additionally return `http_status` and a redacted `business_code`.
   Only integer/string codes consisting of an optional minus and one to six decimal
   digits are retained as strings; other values become null. Vendor text, response data
   and headers are never returned. The caller records these scalar diagnostics in its
   structured rejection/uncertainty warning. A later storage error propagates while the
   committed unknown claim remains recoverable.
5. A repeated invocation of any already-claimed binding returns its current ledger state;
   it never sends again, including after an unknown response, rejection or later settlement.
   Operator review of an uncertain create is required before any separate new attempt.

Submission never sets `provider_call_id`, settles a call or dispatches aftermath. The accepted
parent ID belongs to the binding; it is not a per-call identifier or proof that the phone rang.
The existing Web result path can subsequently derive the explicit child/action pair and
settle a supported result. No provisional task ID is smuggled into the per-call column.

The pure adapter supports both ordinary and scheduled descriptors without changing phone
format. Business calling-window rules are the caller's responsibility; a configured App
scheduler may dial a submitted task, so task submission is a real write requiring live
authorization even if no separate "dial" API is called. Existing one-off S2 permission
does not authorize another live request from this service.

## Reference usage

`YunkeAppTaskSubmitTest::test_one_committed_claim_creates_a_parent_then_web_results_supply_the_per_call_id`
is the runnable consumer. It creates a local pending Yunke call/binding, verifies the claim
is committed before the fake HTTP callback, returns a synthetic accepted task ID, then
collects fake Web results/detail to bind and settle the correct action. Parent ID and
provider call ID stay distinct; queues and notifications are faked and aftermath is disabled.

For example, a synthetic refusal can log `binding_id`, `reason=vendor_rejected`,
`http_status=200`, `business_code="20000"`. These are diagnostics, not acceptance inputs:
a redirect/429 stays unknown even when its actual HTTP status is preserved, and a numeric
code in a 500 response does not make creation successful. No-response/preflight outcomes
have no received diagnostics; absence is not a zero code. Replaying a claimed binding
still makes no request and does not re-log a private response. Old omitted codes cannot
be recovered by this fix or by replaying creation.

Tests use the guarded local testing database without a wrapper transaction, because the
production method must refuse uncommitted outer transactions. Other cases exercise both
configuration/identity gates, empty/mismatched allowlists, descriptor tampering, unknown
responses, failed persistence and authentication rejection without refresh or resend.

## Related files

- `src/VoiceAgent/Services/YunkeAppTaskSubmit.php` — one-request guarded transport.
- `src/VoiceAgent/Repositories/YunkeAppCallBindingRepository.php` — existing committed claims and response persistence.
- `src/Common/VoiceAgent/YunkeApp/YunkeAppTaskAdapter.php` — unchanged pure request/response contract.
- `src/VoiceAgent/Services/YunkeAppResultIngest.php` — separate, default-off result collection.
- `config/services.php`, `.env.example`, `phpunit.xml` — disabled defaults and blank test credentials.
- `tests/Feature/VoiceAgent/YunkeAppTaskSubmitTest.php` — fake transport-to-Web-result lifecycle.
