# Yunke recording copies (T10, default off)

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).

## What it does

The default-off workflow copies a verified Yunke recording into private Media and supplies
fresh signed playback. Transport, ownership/attachment, after-commit enqueueing, bounded
recovery and failed-source holds are implemented and fake-tested. **Engineering is complete;
real CDN/storage/expiry/playback acceptance is still pending.** No real recording has
been downloaded, and all runtime gates remain off.

## How it works

- `YUNKE_RECORDING_COPY_ENABLED` defaults to false. Disabled returns null before DNS/HTTP.
  `YUNKE_RECORDING_ALLOWED_HOSTS` is an exact, comma-separated list of bare lowercase CDN
  hostnames. Its empty default refuses every source even when the gate is enabled. Runtime
  configuration was not changed; enabling requires separate approved live acceptance.
- An enabled request accepts only HTTPS on port 443, without user-info or fragments, and
  rejects whitespace/control characters, IP literals, unlisted hosts and oversized URLs.
  All resolved IPv4 addresses must be globally routable, including rejection of private,
  loopback, link-local, shared and reserved ranges. IPv6-only CDNs are unsupported.
- One fresh cURL handler pins the accepted IP to the original TLS hostname. It verifies
  TLS, disables proxy, redirects, decompression and cookies, supplies no App/Web credentials,
  and never retries or logs in. HTTP timeouts are 20 seconds total / 5 seconds connection;
  DNS uses the host resolver separately. A generic streaming handler must not replace this
  handler because it can ignore cURL's DNS pin.
- Headers are checked before accepting native response bytes. Only 200 is accepted;
  401/403 are explicit authentication failures. The bounded sink refuses writes above
  25 MiB even without Content-Length. A second bounded read checks empty/truncated bodies
  and length mismatches. Bytes must sniff as WAV, MP3 or Ogg audio; a vendor Content-Type
  alone is insufficient. Other formats require a verified sample and explicit support.
- Exceptions carry only a safe reason code, with no previous exception, URL or vendor body.
  Inspector strips all context except method, masked URL and status for configured CDN
  hosts, including the segment label and unfinished requests. Masking is independent of
  the download gate and removes the entire signed path/query and any audio/header content.
- The transport does not identify a call or choose storage. `YunkeRecordingCopy` verifies a
  completed outbound Yunke call with an accepted task, explicit task/child/action IDs,
  scoped keys, original UUID, creation/result hashes and settlement stamp. Refused,
  unknown, unbound or mismatched records are held before download. A per-call lock protects
  concurrent copies; an outer DB transaction is rejected before any storage I/O.
- Storage follows `MediaService::storeFromPath()` and its durable cleanup pattern. Media
  belongs to the call's morph and `ai-call-recording` collection. Production requires the
  configured private GCS disk; private local disks are permitted only in local/testing.
  Keys contain generated UUIDs; Media metadata keeps source/result/content hashes rather
  than URLs, names or numbers. A missing/wrong-size object is an explicit failure.
- A crash between storage and attachment reuses only an owned copy with matching source
  and result hashes, without a second download. The repository rechecks binding, ownership
  and source under the same binding→call lock order as settlement. A concurrent source
  change is not overwritten, and fresh meta stamps survive. Storage/attachment failure
  keeps the source field unchanged; an already-stored unattached copy remains private for
  recovery/review. It is never silently assigned to another call or automatically deleted.
- After attachment, the raw `recording_url` is an internal `media://UUID` pointer. The
  original URL is retained encrypted in `meta.provider_recording_url.encrypted` (Laravel
  Crypt, using the application key), with a separate source hash. It is not a playback URL
  or queue argument. Key rotation must preserve decryption of existing provenance.
- Until a private copy exists — and whenever the copy gate is off — a Yunke row's
  `recording_url` reads as null on every page and API: the vendor's signed, expiring URL
  stays in the raw column for the copy pipeline (`getRawOriginal`) and never reaches a
  browser or the native app. Retell rows keep their provider link as before. Once the copy
  is attached, the model mints a fresh signed application URL on access without querying Media. The
  signed GET route rechecks current call/media ownership and private-disk policy, then
  redirects to a fresh private `MediaService::temporaryUrl()`. Both URLs are short-lived
  (configured TTL, clamped to 1–15 minutes each). A bearer link works in native API audio
  players without a browser session. Missing/expired signatures fail; deleted/reassigned
  calls or media fail. Responses are private/no-store and no-referrer; the vendor source
  is never used as fallback. Existing Retell URL handling and API query budgets are retained.
- Turning the copy gate off prevents new copies but does not revoke already-issued storage
  capabilities. Soft-deleted calls cannot mint/play through the application route; private
  objects remain retained for recovery. Permanent retention/deletion is an operator-owned
  Phase 0 decision and must use the shared MediaService cleanup path, not raw row deletion.
- Both App/Web result processors offer an applied/duplicate call to
  `YunkeRecordingDispatch::enqueue()`. With the copy gate off this does no DB/queue/HTTP
  work. Within an outer transaction, even the claim waits for after commit; rollback
  leaves no claim or job. Recording dispatch failure never rolls back the settled call
  or runs its messaging aftermath.
- A transactional source/identity recheck claims `meta.recording_copy_work`: state
  `queued`, source hash, random lease token and `queued_at_ms`. The queue receives only
  call ID/hash/token. Fresh duplicate offers keep the original claim. An unresolved
  30-minute lease can be replaced for lost-dispatch recovery; this is a copy-work lease,
  never a call timeout, missed outcome, redial or vendor task cancellation.
- The job rechecks its gate, current token/state and source fence, with a 60-second worker
  timeout. A superseded worker does no I/O and cannot fail a newer claim. A busy per-call
  lock releases the job for 30 seconds without spending an attempt: the job runs on its
  lease clock (`retryUntil` = the 30-minute copy-work lease), not on a count of tries, and
  only real exceptions are limited — three, with 60/300-second backoff — for failures a
  later attempt may repair (DNS, fetch, a truncated or empty body, storage, attachment);
  an owned stored copy is reusable. Failures no retry can repair
  (`YunkeRecordingException::PERMANENT`: refused URL/host/address, 401/403, unsupported or
  oversized audio, an encoded body, ownership or source changed, non-private storage)
  **fail on the first attempt** without another download, login or source refresh. Every
  hold persists `failed`, a safe reason and timestamp under the same token and writes one
  redacted warning (call ID, reason code, exception class — never the URL or body), so a
  recording that was never copied does not go unnoticed. Successful attachment atomically
  changes work state to `copied` with the Media pointer.
- The existing Web watch, under its three original gates plus this independent copy
  gate, drains at most **20 additional pending copies** per run using its exact configured
  company/user scope. This drain reads local DB evidence only. Fresh leases, failed work,
  changed sources, unbound/unknown calls and existing copy pointers are excluded/held.
  It adds a `recordings` result with checked/queued/held/errors counts when the copy gate
  is on. Web authentication failure still stops the watch; there is no App login fallback.
- Failed or changed sources require explicit operator review and approved recovery;
  the watcher never erases that hold, guesses a new URL or requeues it indefinitely.
  Inspect the safe work reason and failed queue entry first. After confirming source
  identity/availability and permission, a maintainer may use the transactional repository
  to clear only `recording_copy_work` for an approved retry; owned copies remain reusable.
  Do not reset task/settlement/binding or aftermath stamps. Deployment must use the
  existing asynchronous queue workers, and actual queue latency/URL lifetime need live
  acceptance before the pilot.

## Reference usage

The result processors and watch enqueue the copy job only under the separate gate.
`tests/Feature/VoiceAgent/YunkeRecordingDownloadTest.php` uses
synthetic WAV bytes, fake DNS and
`Http::fake()` with stray requests forbidden. Tests enable gates only in memory. They cover
URL/DNS refusal, pinned request options, HTTP errors, stream bounds, MIME sniffing, EOF
boundaries and safe errors. Native sink/header callbacks are exercised directly; fakes do
not prove actual TLS/CDN delivery. Inspector regressions exercise completed and unfinished
requests without transmitting telemetry.

Run with the project's PHP 8.4 binary:

```sh
php vendor/bin/phpunit tests/Feature/VoiceAgent/YunkeRecordingCopyTest.php tests/Feature/VoiceAgent/YunkeWatchTest.php tests/Feature/VoiceAgent/YunkeWebResultIngestTest.php tests/Feature/VoiceAgent/YunkeAppResultIngestTest.php tests/Feature/VoiceAgent/RetellWebhookTest.php tests/Feature/AgentApi/AgentLeadAiCallerTest.php tests/Feature/Common/MediaCleanupOutboxTest.php
```

Transport/redaction evidence remains **45 tests / 315 assertions**. Copy/private storage,
ownership/concurrency/crash recovery, signed playback/native API and related result/Retell/
Media regressions pass **103 tests / 1072 assertions** in the final combined run, including
after-commit/rollback, duplicate offers, lost leases/stale workers, first-attempt auth holds,
bounded owner-scoped draining and fake Web settlement → queue → audio copy → duplicate
replay without replacing the copy. Pint/diff pass; one existing
PHPUnit XML deprecation remains. Storage uses `Storage::fake()` with explicit private
visibility; most copy tests mock the already-validated audio download, while two lifecycle
cases exercise the real transport through fake DNS/HTTP. No test fetches real
recordings. Explicitly approved CDN, storage permissions, URL-expiry and live playback
acceptance are still required; fake storage is not that acceptance.

## Related files

- `src/VoiceAgent/Services/YunkeRecordingDownload.php` — strict, bounded transport.
- `src/VoiceAgent/Services/YunkeRecordingException.php` — safe failure reasons.
- `src/VoiceAgent/Services/YunkeRecordingCopy.php` — owned private storage and crash recovery.
- `src/VoiceAgent/Services/YunkeRecordingDispatch.php` — after-commit claims, pending drain and failure quarantine.
- `app/Jobs/VoiceAgent/CopyAiCallRecording.php` — default-off ID/hash/token queue job.
- `src/VoiceAgent/Repositories/AiVoiceCallRepository.php` — transactional attachment/provenance.
- `src/VoiceAgent/AiVoiceCall.php`, `YunkeAppCallBinding.php` — Media relation, fresh link and ownership rules.
- `app/Http/Controllers/Main/AiCallRecordingController.php`, `routes/main.php` — signed playback capability.
- `app/Support/Monitoring/RedactingInspectorTransport.php` — configured-CDN masking.
- `config/services.php`, `.env.example`, `phpunit.xml` — independent default-off controls.
- `tests/Feature/VoiceAgent/YunkeRecordingDownloadTest.php` — fake audio/DNS/HTTP checks.
- `tests/Feature/VoiceAgent/YunkeRecordingCopyTest.php` — private storage and playback lifecycle.
- `tests/Feature/AgentApi/AgentLeadAiCallerTest.php` — native API copied-link compatibility and existing query budget.
- `tests/Unit/AgentApp/FcmInspectorRedactionTest.php` — telemetry privacy regressions.
- [Media reference usage](/docs/modules_handbook/shared/media/readMe.md) — shared storage and durable cleanup pattern.
- [Continuation ledger](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md) — remaining software and real acceptance.
