jhonny-editor/code/docs/uxp-hybrid-benchmark.md

# UXP hybrid benchmark and promotion gate

This repository does not ship or enable a native UXP addon. It ships a deterministic
JavaScript benchmark, an adapter contract for a future Adobe SDK build, and a
fail-closed evidence verifier. The production `uxp-plugin/manifest.json` remains
manifest v5 without `enableAddon` or an `addon` declaration.

## Official baseline

Adobe documents Hybrid Plugins as an advanced path for performance-critical C++
work. Premiere first officially supported the feature in 26.2. The SDK is downloaded
from Adobe Developer Console and versioned separately from the host. A candidate
plugin must use manifest v6, declare its `.uxpaddon`, and explicitly request
`requiredPermissions.enableAddon`.

Adobe's bundle layout is strict:

```text
mac/x64/premiere-mcp-benchmark.uxpaddon
mac/arm64/premiere-mcp-benchmark.uxpaddon
win/x64/premiere-mcp-benchmark.uxpaddon
```

Windows evidence must use a Release build so it does not depend on Visual Studio
debug runtimes. Both macOS binaries must be signed and notarized with a valid Apple
Developer ID before distribution.

Official references:

- [Hybrid Plugins overview](https://developer.adobe.com/premiere-pro/uxp/plugins/hybrid-plugins/)
- [Building Hybrid Plugins](https://developer.adobe.com/premiere-pro/uxp/plugins/hybrid-plugins/build/)
- [Hybrid Plugins FAQ](https://developer.adobe.com/premiere-pro/uxp/plugins/hybrid-plugins/faq/)
- [UXP manifest](https://developer.adobe.com/premiere-pro/uxp/plugins/concepts/manifest/)
- [Premiere UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog/)

## Candidate addon contract

After downloading the official SDK, build a dedicated benchmark addon from the SDK
template. It must export one synchronous function:

```js
runBenchmarkKernel(values: Float64Array, iterations: number): number
```

The return value must match `PremiereMcpHybridBenchmark.weightedEnergy()` within the
harness tolerance. No SDK headers or prebuilt binaries are copied into this
repository, and the contract is not an assertion that a native implementation exists.

Use a temporary development manifest—not the production manifest—to declare the
addon and `enableAddon`. Load it through UXP Developer Tool into stable Premiere
26.2 or newer. In the panel's developer console, run:

```js
PremiereMcpHybridBenchmark.run({
  requireAddon: true,
  sampleCount: 30,
  warmupCount: 3,
  iterations: 4,
  inputLength: 131072,
  seed: 1337
})
```

Record at least 20 samples for both JavaScript and native implementations after the
same warmup. Collect process peak working-set memory with the same host-monitoring
method on every target; the UXP heap snapshots returned by the harness are
diagnostic only and are not accepted as process memory evidence.

## Promotion criteria

Copy `benchmarks/uxp-hybrid/evidence.template.json` (schema version 3), validate it
against the adjacent v3 schema, and add one run for each required target: Windows x64,
macOS x64, and macOS arm64. Every run must use the same full source commit, an
identified SDK version, a Release binary SHA-256, matching output, and stable Premiere
26.2+.

Create and structurally verify a hash-only UXP Hybrid header receipt from the
authorized SDK download first. Add the canonical digest printed by the receipt
verifier as `sdkHeaderReceiptSha256`, retain the actual receipt outside this
repository, and give its local path to the benchmark verifier. The receipt must
identify `uxp-hybrid`, and its `source.sdkVersion` must exactly match every run's
`sdkVersion`.

Before submitting schema-v3 performance evidence, record the candidate
development bundle with the separate [Hybrid addon-layout receipt](uxp-hybrid-addon-receipt.md),
then create and verify a [Hybrid CCX archive receipt](uxp-hybrid-ccx-receipt.md).
The v3 benchmark record commits to all three canonical receipt digests. The
benchmark verifier re-reads the supplied local `.ccx`, checks its current
content-free receipt chain including schema-v2 whole-archive ZIP hygiene and
all-entry local-header consistency, and requires every platform run's
`addonSha256` to match its corresponding attested binary. It does not publish
source, binaries, the manifest ID, archive contents, entry names, or local paths.

The frozen `evidence.v1.schema.json` and `evidence.v2.schema.json` plus their
verifier paths remain available for historical records. v1 has no receipt
binding and v2 binds only the SDK header receipt; neither can become a new
package-bound candidate. New submissions must use v3.

The native implementation must improve both p50 and p95 by at least 30% on every
target while keeping peak working-set regression at or below 10%. Verify with:

```powershell
npm run benchmark:uxp-hybrid:verify -- `
  --input .\path\to\evidence.json `
  --sdk-header-receipt C:\sdk-evidence\uxp-hybrid-headers.json `
  --addon-receipt C:\hybrid-evidence\benchmark-addon-layout.json `
  --ccx-receipt C:\hybrid-evidence\benchmark-ccx.json `
  --ccx C:\hybrid-evidence\benchmark-plugin.ccx
```

Only a zero exit code and `promotionEligible: true` support a later PR that adds the
native source, reproducible build files, signed/notarized artifacts, manifest v6, and
addon permission. This receipt binding locally verifies the supplied archive's
hash-only receipt chain and the submitted evidence's SDK and binary identities;
it does not establish access entitlement, compile an addon, validate signing or
notarization, prove UDT or Creative Cloud installation, validate an Adobe portal
record, or prove behavior in a licensed Premiere host. This benchmark PR itself
is not that promotion.