Track L: Inventory API v3 (AIS) and server-side appearance baking (SSB)

[JohnLegionH]

Summary

Adds the two services the current Linden viewer assumes and OpenSim has never had: Inventory API v3 (AIS) and server-side baking (SSB). Both are off by default and each is enabled by one global config line. With both on, the stock Second Life viewer logs in, is textured from the simulator's bakes, and can change outfits, delete, and empty trash - none of which it can do against OpenSim today, because it has no non-AIS path for them. Firestorm works in both modes. Verified with the stock LL viewer 26.3.0 and Firestorm 7.2.5; the protocol was extracted from the LL viewer 26.1.1 source.

223 files changed, 40631 insertions, 231 deletions, in 8 commits. 133 original commits are folded into 4 by path for review navigation (library, AIS, SSB, docs); the commit bodies list what each one folds. Roughly half the insertions are the baking library commit, which includes the vendored avatar_lad.xml and its tests. Three more commits are hygiene done while preparing the PR (neutral test literals, a portable golden harness, docs triage). One commit (b1da081d1e) is the one-line Warp3D build fix that is also offered standalone as #206: it is here because this branch cannot be restored or built outside the org without it, and the two merge clean in either order.

What is in it

1. OpenSimNGC.Appearance.Baking - a standalone compositor library, a port of the LL viewer's texture-layer rules (lltexlayer / llavatarappearance), emitting 5-component J2C (R,G,B,A plus the morph mask). No simulator dependencies; a second consumer (a browser-viewer gateway that logs in as a client) already uses the same library.

2. AIS v3 - region-side caps module (InventoryAPIv3, and LibraryAPIv3 read-only) over IInventoryService, behind IAisInventoryBackend so the same handler can later be hosted on Robust. All 15 operations the viewer uses, extracted with file:line citations into Docs/feature/ais-v3/AIS-V3-SPEC.md.

3. SSB - region module that composites from the agent's wearables and visual params, stores bakes as assets with an input hash (an unchanged outfit re-uses its bakes: measured cold about 2.8 s for five channels at 1024, warm about 70 ms), advertises RegionProtocols bit 0, sends the AppearanceData block, serves the UpdateAvatarAppearance cap, rebakes on COF change and on an edit to a worn wearable; plus a Robust appearance service and agent_appearance_service in the login response.

Enabling it

Region side. These are global: a region section may opt OUT, and is never how you opt in.

[AIS]
    Enabled = true

[Appearance]
    ServerSideBaking = true

A single region opts out with AIS_Enabled = false or ServerSideBaking = false in its own [<Region Name>] section. The per-region AIS key is AIS_Enabled, not Enabled, because a region section holds settings for many modules. Both modules log one INFO line per region at load naming which config decided, for example region Ebony: AIS v3 ON (global).

Robust side. In [ServiceList]:

AppearanceServiceConnector = "${Const|PublicPort}/OpenSim.Server.Handlers.dll:AppearanceServerConnector"

then the service itself:

[AppearanceService]
    LocalServiceModule = "OpenSim.Services.AvatarService.dll:AppearanceService"
    AvatarService = "OpenSim.Services.AvatarService.dll:AvatarService"
    AssetService = "OpenSim.Services.AssetService.dll:AssetService"

and in [LoginService]:

AgentAppearanceServiceURL = "${Const|BaseURL}:${Const|PublicPort}/"

It must reach the connector's port and end with /, because the viewer appends texture/... to it with no separator. Left unset, the login response omits agent_appearance_service entirely and the viewer keeps compositing locally, which is correct for a grid with no such service. The same key exists in config-include/StandaloneCommon.ini.example.

Defaults: [Appearance] BakeSize = 1024 (512, 1024 or 2048) and [Appearance] BakeQuality = 0.85. Changing BakeSize invalidates every stored bake, which is deliberate. [AIS] Enabled and [Appearance] ServerSideBaking both default to false.

Operators should know: enabling AIS routes ALL of a capable viewer's inventory traffic through it; there is no viewer-side fallback, which is why the full operation surface ships together.

Changes to existing behaviour - please look at these first

These are fixes to code that is in develop today. SSB depends on several of them, which is why they are here rather than in separate PRs. The commit ids cited below are from the original branch (feature/ais-v3 on my fork, which is public); they do not exist in this folded branch, but the folded commit bodies list them and the file:line proofs are against this branch.

• Test lifecycle hooks orphaned by the xunit migration. The migration (Feature/xunit tests #197) turned subclasses' [SetUp] methods into overrides of SetUp() and nothing invoked them, so every test relying on a field assigned in setup ran against null. OpenSimTestCase now implements Xunit.IAsyncLifetime and calls SetUp() from InitializeAsync. CoreModules.Tests went from 35 failures to 5. Commit c1fc7fff3e. Proof: Tests/OpenSim.Tests.Common/OpenSimTestCase.cs:43.

• AgentIsNowWearing wiped unlisted wearable slots. The handler replaced the whole wearable array with what the message listed, so any slot the viewer did not mention was cleared. It now merges: unlisted slots are retained, UUID.Zero still clears, and the appearance is saved only on an actual change. Commit 11a2456833. Proof: AvatarFactoryModule.cs:1360 declaring MergeNowWearing, with AvatarFactoryNowWearingTests.

• An appearance save wiped the bake index. AvatarService.SetAvatar deletes every row for the principal before rewriting the appearance-derived keys, and a save fires about five seconds after any outfit change - so every outfit change destroyed the stored bake index and the next bake recomputed all five channels. The delete-all is load-bearing and stays; a preserved namespace was added instead. Commit 1e78b9a706. Proof: Source/OpenSim.Services.Interfaces/IAvatarService.cs:118 declaring AvatarDataKeys, and AvatarService.cs:111 testing AvatarDataKeys.IsPreserved(name). A test pins that a grid which has never baked is byte-identical to before.

• A save from a child presence corrupted the stored appearance. The save resolves items against the region it runs on and then writes to the avatar service; on a child presence that is a write about an avatar another region owns, made from a copy. Observed losing skin, hair, eyes and shirt. A child presence now never writes, and a wearable that cannot be resolved keeps its slot instead of being reset to default. Commit 483c2d7a13. Proof: AvatarFactoryModule.cs:893 (the child-agent write barrier) and :965 (keep the slot). Mechanism written up in Docs/feature/repo-audit/S8-WEARABLE-RESOLUTION.md.

• Wearable types 15 (Physics) and 16 (Universal) were never persisted. The Avatars writer stopped at the legacy bound of 15 wearables, so those two types were dropped on every save even though the wearable table is 17 wide. Commit b0b3c6b671. Proof: IAvatarService.cs:199-203.

• An appearance save was dropped if the agent left inside the save delay. QueueAppearanceSave defers by DelayBeforeAppearanceSave seconds and the handler resolves the ScenePresence only when the timer fires; if the agent had gone, the write was skipped silently and the change died with the presence. A detach followed by a logout inside the window left the stored appearance still wearing the garment. Commit dc4e417bb3. Proof: AvatarFactoryModule.cs:85 subscribing FlushAppearanceSaveOnClose to OnRemovePresence.

• Duplicate Textures folders, created deterministically. XInventoryService.GetSystemFolders filtered f.type > 0, which excludes type 0 - Textures - so every CreateUserInventory call saw Textures as missing and created another one. This is not a race: it happens on every call, and one account here had accumulated eight. The filter is now >= 0. Separately, CreateUserInventory can be entered concurrently for the same principal (it is reachable remotely through XInventoryInConnector) and two overlapping calls can both read "missing" and both create, with no unique key to catch the loser; it is now serialized per principal. Duplicates directly under the root are reported at WARN at login, because nothing self-heals them; suitcase folders are excluded, being legitimate duplicates by type. Commits 3057327361 and 68bfa60735. Proof: XInventoryService.cs:329 now filters f.type >= 0 where develop has f.type > 0 at its :202; :116 takes the per-principal lock; :266 is WarnOnDuplicateSystemFolders.

• ViewerEnvironment.FromWLOSD tested the parameter, not the cast result. A non-array OSD is still non-null, so null reached DayCycle.FromWLOSD(OSDArray) and threw on its first statement. That throw was load-bearing: the legacy WindLight setter called StoreOnRegion immediately afterwards, so fixing the guard alone would have turned a crash into a silent write of a fresh default environment over the region's real one. Both were changed together - the guard tests the cast result, and the setter now refuses a non-array body at the boundary. Commit f6981e12f9. Proof: Source/OpenSim.Framework/ViewerEnvironment.cs:113-114 and EnvironmentModule.cs:758, with ViewerEnvironmentWLOSDTests.

Wire and interface changes:

• IInventoryService gains DeleteFolders(UUID userID, List<UUID> folderIDs, bool onlyIfTrash) alongside the existing two-argument form, which is untouched, as is every existing caller. The LL viewer removes any non-protected folder wherever it sits, while the old signature silently skipped any folder whose parent was not Trash or Lost And Found and still returned true. Implemented across all implementors including XInventoryService, HGInventoryService and HGSuitcaseInventoryService. On the Robust wire the flag is carried as an optional ONLYIFTRASH field that is sent only when it is false, so it is backward-compatible in both directions: an older Robust that does not know the field keeps today's behaviour, and a newer Robust defaults it to true for an older simulator. Commit e2ad97af70. Proof: Source/OpenSim.Services.Interfaces/IInventoryService.cs:121 and :135; XInventoryInConnector.cs:464 reading ONLYIFTRASH; XInventoryServicesConnector.cs:395 sending it only when false.

Security

AIS was put through an external source audit before this PR; all findings are fixed with red-first tests: owner-scoped backend (a valid cap plus another resident's UUID answered 200 before; now a uniform 404), fail-closed body parsing with a 1 MiB ceiling (a malformed slam used to empty the COF), per-(agent, folder) mutation lock, partial-create reporting, generic 500s with server-side logging, and a visited-set on folder traversal.

Docs/feature/ais-v3/AUDIT-1-MALFORMED-LLSD.md is a tree-wide sweep of client-facing LLSD parse sites for the same anti-pattern: 86 parse sites examined, 40 of them client-facing, 0 destructive. One latent defect one edit away from destructive is recorded in its section 5, and it is the ViewerEnvironment fix above.

Tests

project                                  passed  failed  skipped  total
LindenCaps.AIS.Tests                        200       0        0    200
OptionalModules.ServerSideBaking.Tests      115       0        3    118
OpenSimNGC.Appearance.Baking.Tests           31       0        5     36
LindenCaps.Tests                              5       0        0      5
CoreModules.Tests                            76       5        0     81

CoreModules: the five failures are pre-existing on develop and unrelated - AvatarFactoryModuleTests.TestSetAppearance, AvatarFactoryModuleTests.TestSaveBakedTextures, InventoryArchiveLoadTests.TestLoadIarCreatorAccountPresent, InventoryArchiveLoadTests.TestLoadCoalesecedItem, InventoryArchiveLoadTests.TestLoadIarV0_1AbsentCreator. Before the lifecycle-hook fix in this PR that project had 35.

Golden-image tests compare the compositor against reference bakes captured from the LL compositor. The fixtures are real avatar assets and are not in the repo; without them those eight tests SKIP, with a reason naming the script and the variables it needs. Golden/fetch-fixtures.sh generates them from any grid - see its header for the six required environment variables and a worked example.

Not carried: one NPC appearance test that lives in a Phlox test project develop does not have.

Verified live

Running grid-wide on a three-region hypergrid-enabled grid (two 256 m regions and one 1024 m var region) since 2026-09-07. Firestorm 7.2.5 on all three regions; the stock LL viewer 26.3.0 on a 256 m region (it cannot enter var regions). Real-content coverage: every wearable type including tattoo, alpha, universal, physics, layered multiples per type, and the BoM aux channels. Docs/feature/ais-v3/A5-LIVE-CHECKLIST.md is the operator verification script.

Known limitations (all with the flags ON; nothing changes with them off)

• NPCs: on an SSB region NPCs render correctly in Firestorm but as a cloud in the stock LL viewer, and an owner rebake can delete a bake an NPC clone still references. The fix (bake NPC ids, reference-safe supersede) is planned next; I will push it to this branch if it is still open, or follow up.
• Viewers log a folder-version "possible version mismatch ... adjusting" line on each wearable save (the viewer expects one more increment than AIS returns). Self-corrects, nothing lost.
• A region with SSB off collapses a layered outfit to one wearable per type on a COF change made there. Mixed grids should treat the flags as all-or-nothing.
• POST items-create answers 501 by design: the viewer's own builder for it is compiled out (USE_AIS_FOR_NC is never defined), so no stock viewer sends it. The handler refuses the whole body before writing anything rather than creating an item with no asset behind it.
• A slam is not transactional across the inventory service (it needs a service-side SlamLinks). Links are created before the old ones are removed, so a folder never holds fewer links than it started with, but between the last create and the last remove a reader racing the slam sees both sets. The per-(agent, folder) mutation lock closes that within one region process only. Likewise the CreateUserInventory lock is per Robust process.
• InventoryFolderBase.Version is ushort against an int(11) column, so it wraps past 65535 and any version comparison then picks wrongly. Pre-existing; AIS makes it more visible because its resolution rule reads that value.
• The duplicate-system-folder fix (>= 0) has no unit test: Tests/OpenSim.Services.InventoryService.Tests is outside the solution and does not build (NU1605 package downgrades against OpenSim.Tests.Common). Resurrecting it is a follow-up.
• Do NOT add a unique index on (agentID, type) to inventoryfolders: HG suitcase folders are legitimate duplicates by type, and HGSuitcaseInventoryService.CreateSystemFolders builds a full set of them. A candidate shape is (agentID, parentFolderID, type), not settled and not recommended yet.
• Bake assets accumulate until expiry; the R,G,B,A,M component order is empirical (the SL bake service source is not public) and verified against reference bakes, not against a citation.
• On a hypergrid Robust, AvatarServices = RemoteAvatarServicesConnector, so the bake-index preservation runs inside Robust: that fix is live only after Robust is redeployed, not after a region-only deploy.
• The AIS system-folder resolution scans the suitcase too. Suitcase COFs sit at version 1 so the root COF always wins today, but nothing enforces that; if a suitcase COF ever overtook the root one, a local user's outfit would resolve into their suitcase.
• Folder thumbnails and the favorite flag are accepted by AIS and silently dropped, this tree having no column for either. Folder deletion is refused by the hypergrid inventory services.
• Whether LibreMetaverse exposes RegionProtocols from RegionHandshake to a gateway is still open; it matters only to non-viewer clients.

Third-party content

Source/OpenSimNGC.Appearance.Baking/THIRD-PARTY-NOTICES.md: avatar_lad.xml (LL viewer 26.1.1, LGPL 2.1 with the Linden linking exception, unmodified, SHA-256 recorded) and 56 parameter-mask TGAs, each with a SHA-256 verified byte-for-byte against the viewer tree. The notice also records that the viewer commit id named in the design docs could not be confirmed from the checkout used and is a claim rather than a fact.

Two decisions I would like from you

1. Library placement: OpenSimNGC.Appearance.Baking is in-tree today (ADR-003). It has no simulator dependencies and a second consumer already exists, so it is a candidate for an NGC NuGet package. Your call; nothing in this PR prevents either.

2. AIS hosting: this is Phase 1, region-side. IAisInventoryBackend is the seam for hosting the same handler on Robust ("inventory out of the simulator"). I would like your view on where that should live before I build it.

Related: #206 is the Warp3D restore fix on its own. The identical change is commit b1da081d1e here; whichever merges second is a no-op.