# MarvelPBX Recording Management

Phase 9R1 establishes a recording-management boundary around the existing Grandstream UCM HTTPS resolver and REC transport. It does not copy recordings into CRM, persist physical paths in `recordingurl`, enable upload/delete, or grant production capabilities automatically.

## Architecture

```text
PBXManager call reference
→ deterministic UCM CDR resolution
→ exact getRecordInfosByCall confirmation
→ exact authenticated REC catalog match
→ normalized RecordingReference
→ RecordingPolicy
→ playback/download service or future export/import worker
```

`RecordingReference` exposes recording identity, tenant/call reference, source/storage class, availability, media metadata and capability booleans. It never exposes a UCM/NAS path, credential, cookie or raw API result.

## Resolution and availability

Resolution reuses the proven `sourceuuid` → exact CDR tree/node → `AcctId` → `getRecordInfosByCall` chain. The confirmed recordfile basename must occur exactly once in an authenticated REC catalog. Multiple CDR trees, multiple recording nodes or multiple catalog locations are ambiguous; the service never chooses the newest or closest filename.

UI availability states are `AVAILABLE`, `PENDING`, `NOT_FOUND`, `ARCHIVED`, `UNAVAILABLE`, `AMBIGUOUS` and `REJECTED`. List rows with a potentially resolvable source reference are `PENDING`, not falsely `AVAILABLE`. The detail view performs the controlled server-side resolution and displays the final state.

## Catalog and filtering

The Marvel list uses parameterized server-side filtering for date, call status, direction, agent/user, duration, call reference and coarse recording availability. Existing authorized CRM enrichment supports contact/account filtering. Canonical queue and tenant catalog columns are not present in the current Vtiger read view, so queue/tenant catalog filtering is `FOUNDATION_READY`, not invented from caller or filename data. Raw UCM listings never reach the browser.

## Capability status

| Capability | Phase 9R1 status |
| --- | --- |
| Deterministic resolution | IMPLEMENTED |
| Catalog/list filtering | FOUNDATION_READY |
| Browser playback proxy | IMPLEMENTED |
| Separate download authorization | IMPLEMENTED; no default grant |
| Upload/import | FOUNDATION_READY; write side DEFERRED_TO_9R2 |
| Single export | FOUNDATION_READY; DEFERRED_TO_9R2 |
| Batch export | DEFERRED_TO_9R2 |
| Privilege enforcement | IMPLEMENTED |
| Security audit | IMPLEMENTED for playback/download |
| Retention/legal hold | FOUNDATION_READY |
| Physical delete | DEFERRED_TO_9R2 and disabled |
| AI access | FOUNDATION_READY; no provider call |

Upload policy accepts only an explicitly privileged, bounded, server-MIME-validated media import associated with an existing call. The actual storage write, malware hook and version/reassociation transaction are deferred. Export policy requires an explicit filter and bounded count; no unrestricted export-all operation exists.

## Current parity limitation

The standalone `ucm_recording_sync.php` proves resolution but does not update `recordingurl` or install/update the Marvel module. The installable package contains the playback service and UI integration; the active Vtiger deployment must be updated/configured separately before browser parity can be claimed. Runtime resolution is preferred over a fragile physical URL database write.

No CEM authority, popup, listener, AMI lifecycle or recording storage behavior is changed by Phase 9R1.