surface

Status: Current implementation reference. Surface ownership is under review for the runtime dataset rebuild; this page is not design authority for the target runtime dataset.

surface.elonn.local is the surface persistence service for Elonn. Production is surface.elonn.com.

Current implementation: Surface is upstream of world and is the source of truth for the surface layer. World reads from surface to build the surface_runtime portion of the current compatibility contract. Surface does not own social data, maps data, or identity.

Owns

• Surface records — what surfaces exist, their type, service binding, content source, permissions, and flexible JSON state
• Stack records — the three canonical stacks with their ordered membership and focused surface
• Stack items — the ordered position of each surface within its stack
• Surface placements — placement mode (stacked, docked, detached, field-anchored) per surface
• Surface sessions — a session token per surface for lifecycle tracking

Canonical stacks

stack_key	stack_type	Role
carry_primary	carry_stack	Center workspace — the main surface stack
left_context	context_stack	Left rail — runtime and user surfaces
right_context	context_stack	Right rail — service navigation or field controls

Surface types

Durable workspace types:

web_surface, document_surface, map_surface, calendar_surface, conversation_surface, community_surface, event_surface

Runtime/context types:

profile_surface, dashboard_surface, service_nav_panel

Role in the stack

surface.elonn.local  ←→  world.elonn.local  →  runtime (web, android, ipad)
       ↑                                               |
       └───────────────────────────────────────────────┘
                    (focus / reorder writes)

1. World reads GET /runtime from surface and supplies trusted member context in X-Elonn-Member-Id
2. World embeds the payload in /world/session as surface_runtime
3. The runtime renders the carry layer from surface_runtime
4. Focus, reorder, and placement writes go through World, which derives member context and relays it to Surface

Runtime reads without member context are rejected.

Surface persists runtime state; world composes and relays it; runtimes render it.

Runtime reads are additive. Surface may create missing member stack rows or placement rows required for existing surfaces, but it must not seed demo surfaces, reset an existing member stack, reorder existing stack items, overwrite valid focus, or replace existing placements during a read.

For the Web runtime proof path, see Current State.

Finding surfaces

Surface is the runtime object authority for findings. Find emits normalized findings; World passes those findings to Surface; Surface creates individual finding_surface objects with service binding, runtime state, permissions, and placement.

Finding surfaces should become independently movable objects. Surface owns their persisted placement:

• mode
• x/y position
• width/height
• z order
• focus

Web can drag or resize optimistically, but the authoritative write goes through World to Surface.

Readiness

Surface exposes GET /ready as its readiness check. It returns elonn_surface when the database is reachable and the service can answer runtime reads.

Verification

Surface has a local smoke test suite:

bash surface.elonn.local/test.sh

The smoke tests verify the runtime contract rules that runtimes and World depend on:

• canonical surface types are enforced
• runtime reads without member context are rejected
• X-Elonn-Member-Id: 1 and X-Elonn-Member-Id: 2 resolve to separate stack rows
• runtime surfaces and stacks include the normalized stable fields
• object-valued runtime fields serialize as JSON objects, not empty arrays
• runtime reads preserve existing stack order and focus
• changing focus for one member does not affect another member

Routes

GET  /surfaces
POST /surfaces
GET  /surface/{id}
GET  /ready
GET  /runtime
GET  /runtime/surfaces
GET  /runtime/stacks
GET  /runtime/stacks/{stack_key}
POST /runtime/stacks/{stack_key}/focus
POST /runtime/stacks/{stack_key}/reorder
POST /runtime/surfaces/{id}/placement

CORS is open to web.elonn.com and world.elonn.com (and their .local equivalents). Surface makes no outbound calls — it is a purely reactive service.

Critical distinction

A surface (a persistent, service-backed contextual environment) is distinct from a panel (service-owned content loaded inside a surface via content_source.url when content_source.kind is runtime_panel).

Term	Meaning
surface	persistent contextual environment within a stack; owned by surface.elonn.local
panel	service-owned content loaded inside a surface via content_source.url when content_source.kind is runtime_panel; owned by the source service

Surface sessions must always be qualified — do not use "session" alone.

Canonical terms

• surface — persistent contextual presentation layer
• stack — ordered container for surfaces with one focus surface
• panel — service-owned content loaded inside a surface
• session — always qualify: surface session