feat(collaboration): live co-editing session endpoints for Studio saved maps/apps

[mikemcdougall]

Specifica

Type: Feature
Parent epic: honua-io/honua-studio#1
Workstream: Hawaii flagship demo
Owner repo: honua-io/honua-server
Affected repos: honua-io/honua-server, honua-io/honua-sdk-js, honua-io/honua-studio
Priority: P2
Phase: Beta

Context

The JS SDK ships an experimental saved-map collaboration client (src/collaboration: transport-neutral session API, snapshot reducer) currently running only on a fixture transport — its docs state a WebSocket/WebTransport adapter arrives 'when the server endpoints land.' Asynchronous collaboration already works through the Studio package lifecycle (drafts, immutable versions, comparisons, publish, rollback), but live co-editing of a map/app session has no server surface. honua-studio (the open-source builder) and console both need it so multiple users can edit the same composition with Honua as the conduit.

Requirements

• REQ-001: Session endpoints (create/join/leave) scoped to a Studio content item or draft, with authorization consistent with the Studio lifecycle surface.
• REQ-002: A WebSocket (or WebTransport) event stream carrying the SDK collaboration contract's session events — presence, state deltas, snapshot recovery — compatible with reduceSavedMapCollaborationSnapshot.
• REQ-003: Persistence bridge: a live session can be checkpointed to a Studio draft/content version at any time; session end offers checkpoint.
• REQ-004: Conflict semantics documented and enforced (server-ordered deltas; late joiners get snapshot + tail).
• NFR-001: Sessions survive transient disconnects with resumable cursors consistent with the SDK realtime module's resume semantics.

Acceptance Criteria

• The SDK collaboration client passes its existing contract tests against the real transport (fixture transport swapped for WebSocket adapter).
• Two clients co-edit a saved map with convergent state and checkpoint to a Studio version.
• Session authz honors the same identity model as the Studio lifecycle endpoints.

Dependencies

• Studio package lifecycle (shipped, Backend: Studio package lifecycle API for Console authoring #1180); SDK collaboration contract (shipped, experimental).

Validation

• Contract tests against the SDK client; integration tests for checkpoint/rollback interplay; load test for session fan-out.

[github-actions]

Capability key needed

This issue doesn't have a Capability Key(s) value yet. Adding one lets us tie the ticket to the cap/<category> label taxonomy and surface it in the capability evidence roadmap.

Comma-separate one or more keys, e.g. editing.feature-edits, geocoding.single-line. If you only know the general area, the category slug alone is fine (e.g. editing, serve-ogc).

Current categories: ai, alerts, analytics, caching, channels, collaboration, control-plane, demo, disaster-recovery, discovery, editing, enrichment, extensibility, field-ops, geocoding, identity, import, ops, printing, process, raster, routing, scene, serve, static-map, streaming, styling, temporal
(see docs/gis/data/capability-categories.seed.json).

This is advisory — no action is required to keep the issue open.