#3532 [GUI] Export Official App Contracts For Tray And Web Companions

Description

## Problem And Result

Optional Tray and browser companions can drift from the official App after App/Control updates if they keep their own model/context catalogs or patch bundled frontend files. This opt-in offline tool exports the App's own capability metadata and a byte-identical frontend candidate, then verifies the complete asset inventory against a fresh App/Control source identity.

Related scope discussion: #3531. **Ready For Review; maintainer scope agreement is still pending and is not assumed.** Existing Tray #3365 and Local Model Extension #3373/#3369 keep their own scopes. This is the reusable compatibility/export layer extracted from a private integration, not a proposal to move that integration's account, deployment or external-client synchronization into Strata.

## Approach And Compatibility

All changes are new files below `tools/app-surface-contract/`, based on main `9de04cd44e927a9a3df6bbc0e94fc1be8b844ba4`. The default App, engine, server, setup, installer and updater files are unchanged. No dependencies or defaults are added.

The explicit reader uses the installed host's `findControl`, selected bundled Python, read-only `strata_models` and `NATIVE_FIELDS`. Recommendations and Context values come from official metadata. Nested allowlists exclude config, paths, commands, credentials and unknown fields. Reasoning Effort remains in the official Composer; update installation remains in App/Control. Unknown App versions, changed tested contracts, replaced sources/Python or changed selected Control fail with safe `needs_validation` output.

Export creates a new directory outside the App, copies the original frontend without rebuilding/injection, checks source identity again and writes a manifest. Verification requires the caller's exact manifest SHA256, checks every path/size/hash and fresh source identity, and rejects links, traversal, extra files and changed bytes. There is no engine/Web host startup, inference, installation, updater, daemon or deployment activation in the production commands. The separately invoked anonymous UI fixture is loopback-only and rejects every mutation, including Chat.

Checksums describe the trusted installation the user supplied; they do not replace vendor signatures. A verified candidate is not a deployed or authenticated Web service and does not establish a model's loaded state, allocated Context or future compatibility.

## Examples

These are **anonymous simulated states rendered from unchanged official App 0.2.1 assets** through the included read-only fixture. The hardware label and API connection are examples, not this contributor's machine/account/model. No original private screenshot, account details, credentials, personal paths or EXIF/comment metadata is included. They do not demonstrate inference, GPU memory allocation or performance. Reproduction commands are in the README.

The Models page's initial 64K is the official download recommendation, separate from the example API connection's 200K capacity. The Effort options are the official Composer's own UI.

![Official Context Choices](https://raw.githubusercontent.com/medking82/Strata/e53b903456c4f7fe82e356dcd335b5feeb25a446/tools/app-surface-contract/examples/context.jpg)

![Official Composer Effort](https://raw.githubusercontent.com/medking82/Strata/e53b903456c4f7fe82e356dcd335b5feeb25a446/tools/app-surface-contract/examples/effort.jpg)

## Validation

Candidate `e53b903456c4f7fe82e356dcd335b5feeb25a446`, Windows x64, Node v24.18.0. Commands omit the workstation's windowless-runner wrapper.

**Passed:**

- From the repository root: `node --test tools/app-surface-contract/contract.test.mjs tools/app-surface-contract/assets.test.mjs` — **15 passed, 0 failed, 0 skipped**. Disposable fixtures cover official value projection, nested privacy, selected-Control/source/Python changes, safe error handling, inventory tampering, pinned manifest rejection, path/link bounds, no overwrite and interrupted export.
- From `apps/host`: `node --test tests/native-settings.test.mjs tests/native-settings-response.test.mjs tests/native-settings-file.test.mjs` — **8 passed, 0 failed, 0 skipped**. Uses the existing host dependencies installed by `npm ci --ignore-scripts --no-audit --no-fund --prefer-offline`; no lockfile change.
- Actual installed official App 0.2.1 / selected Control 0.1.46.3: `cli.mjs export --host <installed-host> --output <new-candidate>` and `cli.mjs verify --host <installed-host> --candidate <candidate> --manifest-sha256 <returned-pin>` — **70 official frontend files exported and verified**. All 13 recorded private/client config file hashes were unchanged. This was metadata/asset acceptance only, not App launch or model inference.
- Anonymous fixture: actual browser rendering of Models, the eight official Context choices, the example connection and official Effort menu. HTTP GET `/` returned 200; POST `/api/chat/stream` returned 501. Both JPEGs were visually inspected and contain only JFIF metadata, without EXIF or comments.
- `git diff --check` and `git diff 9de04cd4 -- . ':!tools/app-surface-contract'` are empty. Existing product source and defaults are byte-identical to the base.

**Failed / Resolved:**

- The first optional host regression invocation lacked `esbuild`, then used the repository root rather than the host working directory. After the locked dependency setup and correct `apps/host` working directory, all 8 checks passed. No unresolved product-test failure remains.

**Not Run / Limits:**

- Real model download, cold load, inference, GPU allocation, unload/idle timing, App update/reboot and native Tray interaction. This helper does not implement those operations.
- CUDA/HIP/SYCL/Metal builds: no backend source is touched.
- macOS/Linux installed-App acceptance and real process timeout termination on those platforms. Unit metadata runners are injected fixtures; the actual successful Python call was exercised only on Windows.

Maintainer help requested: confirm the opt-in tool scope in #3531 and whether it belongs beside the existing companion proposals. Targeted macOS/Linux installed-host acceptance is welcome if those platforms should be supported. This PR makes no claim that the existing Tray/Extension proposals are accepted or that a future App version is compatible.