feat(inference): persist and manage browser model artifacts

[JArmandoAnaya]

Summary

• add a validated schema-v1 client for https://models.robomous.ai/registry/v1.json and intersect it with a build-owned browser model admission catalog
• persist verified model weights in Cache Storage, re-verify them on activation, activate ORT lazily, and preserve the Phase F suggestion executor
• add browser-model lifecycle UI for source, license, download size, acquisition, session-only fallback, readiness, failure, and removal
• prove reload reuse, route-level CDN outage, corruption handling, quota failure, removal, explicit-download behavior, server isolation, and real EfficientSAM inference in Chromium

Live registry and admission

The implemented live schema is registry schema_version: 1: a models array containing id, name, immutable revision, model_ref, and a relative immutable manifest path. The immutable manifests are also schema v1 and describe source revision, ONNX runtime contract, capabilities, and encoder/decoder artifacts. The current manifests expose source metadata but no license field, so legal identity remains pinned by the build admission record and any future manifest license field must match it.

The live registry contained five entries during implementation:

Model	Revision	Manifest / metadata	Artifact roles	Current runtime compatibility	Admitted
EfficientSAM-Ti	b19782d049c0-843761ca46f4	v1; EfficientSAM source; build-pinned Apache-2.0	encoder, decoder	exact Phase F graph contract	yes
MobileSAM	359e37f2b168-7983079ab060	v1; MobileSAM source; no live license field	encoder, decoder	different graph contract; no adapter in this build	no
EfficientViT-SAM-L0	e48dd681ba4b-1d3ba86d781b	v1; EfficientViT source; no live license field	encoder, decoder	different graph contract; no adapter in this build	no
SlimSAM-77-uniform	7f2c646efd21-e6eb3c03cdbd	v1; SlimSAM source; no live license field	encoder, decoder	different graph contract; no adapter in this build	no
SAM2.1-Hiera-Tiny	7f000e65546d-6dbe21e6e60e	v1; SAM2 source; no live license field	encoder, decoder	different graph contract; no adapter in this build	no

Unsupported entries are parsed as registry data but never become catalog entries or installable UI. Phase H can admit another release only after its exact execution contract is implemented and pinned.

Trust and persistence model

• Registry presence is discovery, not trust. The admitted EfficientSAM release pins ID, revision, model reference, immutable manifest path, runtime/capability contract, upstream source revision, Apache-2.0 identity, artifact filenames, byte counts, and SHA-256 digests in the application build.
• Paths must remain relative to the configured VITE_MODEL_CDN_BASE_URL; traversal, encoded separators, absolute URLs, and metadata mismatches fail closed. Remote metadata never supplies executable code or imports.
• Cache Storage namespace: visionset-browser-models-v1.
• Storage-only keys use a synthetic non-network origin and include model ID, immutable revision, and SHA-256: https://cache.visionset.invalid/__visionset_model_cache__/<id>/<revision>/sha256/<digest>.
• Acquisition verifies every artifact's admitted byte count and SHA-256 before the cache is opened or the first write occurs. A partial write is rolled back and never counts as installed.
• Activation reads only local cache entries, re-verifies admitted size and SHA-256, and only then creates the existing Phase F runtime/executor. Corrupt or partial cache entries are deleted and never cause an automatic download.
• Runtime/session and image embeddings remain memory-only. ORT workers are created lazily when Suggest needs an installed preferred model, and removal disposes the active runtime before deleting that model revision's entries.

The admitted live artifacts are:

• https://models.robomous.ai/models/efficient-sam-ti/b19782d049c0-843761ca46f4/encoder.onnx — 24,799,777 bytes — b19782d049c09a8f1cc36ccc6029264ca23c8ac35e6379fd9ef9f1bc6d81e7f2
• https://models.robomous.ai/models/efficient-sam-ti/b19782d049c0-843761ca46f4/decoder.onnx — 16,501,901 bytes — 843761ca46f4aa00b09fdcf0c94271321f76eece092a744296c742d682a86172

User-visible behavior

• Missing weights are fetched only after Download to this browser. Page load, editor load, arming Suggest, opening This device, and restoring a preference perform zero artifact GETs.
• A complete cache survives runtime recreation/reload, preserves a known browser preference, and activates without another artifact GET. A registry or artifact-route outage does not block an admitted cached model.
• A known but uninstalled preference remains on This device with an explicit download/retry action. Only an unknown/unadmitted ID follows the stale-preference fallback.
• Remove from this browser invalidates the target, disposes its worker/runtime, clears prepared state with disposal, and deletes both admitted artifact entries. It does not select or download another model.
• Cache Storage absence or quota/write failure falls back to a truthful Ready for this session, but it was not saved in this browser state. Reload then returns to uninstalled.
• Server inference stays independent of registry/CDN/catalog health and continues to use POST /inference/suggest. A ready browser target continues to make no inference HTTP request.

Verification

• bash scripts/verify_npm_packages.sh
• pnpm test:scripts — 160 passed
• bash scripts/build_dist.sh && VISIONSET_REQUIRE_WHEEL=1 uv run pytest tests/packaging — 16 passed; installed wheel served successfully
• bash scripts/check.sh docs — docs build, deterministic projection, and 5,986 internal links passed
• bash scripts/check.sh — 4,895 Python tests passed / 34 skipped; frontend build, 3,701 package tests, lint/type/boundary/generated gates, 287 app E2Es / 1 opt-in smoke skipped, 5 real-server cycle tests, 23 media E2Es, and 6 browser-runtime E2Es passed
• Hermetic browser-model E2E covers real EfficientSAM suggestion, persistent reload reuse with zero additional artifact GETs, CDN route failure, removal plus reload, and quota/session-only behavior using real Cache Storage.
• Mutation checks were planted and killed for automatic download, admission bypass, manifest-as-trust-anchor, cache-before-verification, skipped cache re-verification, corruption-triggered fetch, partial readiness, key identity loss, reload fetch, incomplete removal/disposal, unsupported-model exposure, preference regressions, registry-outage coupling, metadata mismatches, and package weight leakage.

Real CDN smoke

The opt-in Chromium smoke fetched and validated the live registry and immutable manifest, downloaded and verified both admitted artifacts, created the real runtime, prepared an image, suggested successfully, recreated the page/runtime, re-verified the persistent cache, and suggested again with zero artifact GETs after reload.

• persistent entries: 2
• persistent bytes: 41,301,678
• cold acquisition plus activation: 6.07 s
• cache lookup: 0.3 ms
• cache read: 29.2 ms
• SHA-256 verification: 32.7 ms
• reload activation from cache: 724 ms

These are observations from one development machine, not CI performance gates.

Known limitations

• Browser persistence is best-effort; the browser may evict Cache Storage, after which another explicit download is required.
• This build admits only EfficientSAM-Ti. It does not rank, benchmark, or add adapters for the other live registry models.
• There is no automatic revision update or old-revision garbage collection.
• Multi-tab coordination and broader offline/device-loss hardening remain Phase I work.

Provenance compatibility

The live registry and immutable manifest publish robomous/efficient-sam-ti@b19782d049c0-843761ca46f4; Phase G validates that spelling as registry metadata (registryModelRef). Annotation provenance remains the Phase F contract, efficient-sam-ti@b19782d049c0-843761ca46f4 (annotationModelRef). The identical admitted artifact revision therefore produces the same accepted-annotation model_ref before and after this PR.

Artifact verification and persistence are separate typed stages. Raw downloader output must pass the build-owned size/SHA checks before it can be persisted, retained for the session, or passed to ORT. Integrity failures hard-fail; only persistence failures may use the verified session-only fallback.