# QNE Main Node Shadow System Doctrine V1

Status: current superseding operational doctrine
Date: 2026-06-07
Layer: Layer A/B bridge doctrine for current QNE node architecture
Workspace anchor: qne-node-v00505

This doctrine supersedes previous QNE node/system doctrine for main nodes, master
nodes, seed nodes, QNENodeSkills, QNESceneData, mobile/tablet clients, and
node-hosted shadows. Older doctrine remains useful history, but this document is
the current source of truth for implementation decisions in the next node work.

## Summary

The QNE system is centered on a minimal capable QNE node. A capable node owns
identity, persistence, QNE P2P, QNENodeSkill lifecycle, DHT participation when
appropriate, and node-hosted device shadows.

Mobile, tablet, and similar apps are not QNE runtimes. They are native QNE UI
surfaces that render QNESceneData, return user actions, and bridge approved
native capabilities. Executable behavior remains on capable nodes as
QNENodeSkills.

## Core Naming Doctrine

Use QNE all caps in new mixed-case names.

The internal executable capability trait is QNENodeSkill. Do not use QNESkill as
a separate product term. Client/mobile render payloads are QNESceneData, not
skills. Node-side device presence is QNEMobileShadow. Platform bridge code is
QNEMobileAdapter.

Existing lowercase binary, crate, and protocol names such as qne-node, qne-p2p,
and CLI commands may remain lowercase.

When code changes begin, rename the existing Rust trait from QneNodeSkill to
QNENodeSkill directly. Do not leave a temporary compatibility trait or alias.

## Node Doctrine

A QNE node is the durable execution and authority unit.

Every capable node owns:

- a node UUID
- a persisted QNE P2P static key under persist/secrets
- one full QNE filesystem layout
- QNE P2P transport
- QNENodeSkill lifecycle
- local policy enforcement
- optional DHT participation
- optional user hosting
- optional QNEMobileShadow hosting
- optional repository, seed, or master roles

The base node should remain small. It provides identity, persistence, QNE P2P,
DHT hooks, QNENodeSkill lifecycle, configuration, startup/shutdown, and policy
boundaries. Features such as user hosting, mobile shadows, repository service,
DHT service, UI service, network tests, and payment/account flows are
QNENodeSkills or node roles built on that base.

A node update stops the service, preserves identity and persist, installs the new
binary, restarts, restores QNENodeSkill state, and resumes network presence.
Hot-swapping the base node is not the doctrine.

## QNENodeSkill Doctrine

A QNENodeSkill is executable QNE behavior running on a capable QNE node.

A QNENodeSkill has:

- a unique sequence number
- a stable skill name
- numbered actions
- message send/process/receive methods
- lifecycle start/restore/shutdown methods
- pack/unpack persisted state
- access only through node-provided context and policy

QNENodeSkills may be invoked locally or over QNE P2P. The architecture must not
split into separate local skills and network skills unless a concrete need
appears.

QNENodeSkills can produce QNESceneData, request capabilities, update DHT records,
route messages, host users, manage storage, or coordinate workflows. They do not
execute on mobile/tablet apps.

## QNESceneData Doctrine

QNESceneData is declarative render data produced by a QNENodeSkill.

QNESceneData may describe windows, layout, text, images, controls, actions,
media references, scene state, capability prompts, and user input targets.

QNESceneData must not contain downloaded executable code, mobile-side plugins, or
arbitrary scripts. This keeps iOS and Android clients reviewable and makes the
architecture clear: the node computes; the client renders.

The mobile app receives QNESceneData, renders it with reviewed native code, and
returns action/capability results to the node.

## QNE Color Doctrine

QuickNEasy UI color specifications are standardized on OKLCH. Design colors are
to be stored, named, and reviewed as OKLCH lightness/chroma/hue values so
relative perceived color strength remains stable across hues. Renderers and
adapters convert OKLCH to their target output format, such as Skia sRGB `Color`
or browser CSS, at the adapter edge.

Legacy RGB constants may remain until touched, but new or changed UI colors
must not be specified by ad hoc RGB/HSL values unless they are direct technical
outputs from an OKLCH conversion. The standard Personal Assistant window
title-bar color is pastel green.

## QNEMobileShadow Doctrine

A QNEMobileShadow is a node-level always-on shadow for approved mobile, tablet,
browser, kiosk, or thin-client devices.

It is not a full node clone and not a user home. It is a durable node-side
mediator between QNENodeSkills, users, members, approved devices, remote nodes,
and delegated DHT presence.

A shadow stores per-device state under node persist, not under
QNE/users/<user-uuid>.

A shadow record includes:

- device UUID
- device public/static key binding
- adapter kind, initially Android
- approval/revocation state
- permissions
- active session state
- queued scene updates
- queued actions
- capability request/result state
- delegated DHT presence state
- audit markers for sensitive actions

A device may serve the node owner, a member, or a pass-through user/member
session according to node policy. The shadow is created at node level so it can
mediate these relationships instead of being owned by one user directory.

## Home Node Pairing Doctrine

The user-facing name for the fixed capable node that owns a person's device
shadows is Home Node.

The intended mobile/tablet first-connection flow is QR pairing from the Home
Node. The Home Node creates a short-lived pairing offer containing network ID,
manifest hash, Home Node UUID, reachable UDP endpoint, Home Node static public
key, pairing nonce, and expiry time. The QR code is only a bootstrap and
location mechanism; it is not the permanent credential.

The mobile app scans or receives the pairing payload, connects to the Home Node
endpoint over QNE P2P, presents its device UUID and static public key, and the
Home Node writes or confirms the QNEMobileShadow allowlist record. Normal
reconnect uses the saved Home Node endpoint and identity. If the endpoint later
changes, discovery can be added through LAN discovery, fixed seed lookup, or
delegated DHT presence.

The first headless implementation may print the pairing payload from CLI. A
later UI/mobile adapter may render the same payload as a QR code.

## QNEMobileAdapter Doctrine

A QNEMobileAdapter translates generic shadow requests into platform-specific
client behavior.

The initial adapter target is Android. Later adapters may include iOS,
tablet-specific variants, browser, desktop thin client, and kiosk/TV surfaces.

The adapter boundary handles camera, microphone, files, photo picker, sharing,
notifications, biometrics/device unlock confirmation, justified location use,
platform permission prompts, and platform-specific scene rendering details.

The adapter does not execute QNENodeSkills. It only renders QNESceneData, sends
user actions, and returns native capability results.

## Mobile And Tablet Doctrine

Mobile and tablet apps are thin QNE UI surfaces.

They provide device identity proof over QNE P2P, secure transport, scene
rendering, touch/keyboard/camera/media input, native permissions, temporary
cache, and reconnect/resume.

They do not provide durable DHT participation, local QNENodeSkill execution,
background server behavior, downloaded executable behavior, or independent QNE
authority while offline.

The home/main node participates in the network on behalf of the device through
the QNEMobileShadow.

## DHT Doctrine

DHT lookup keys remain typed. Node UUIDs, member IDs, user UUIDs, and device
UUIDs must not be conflated.

DHT records may include node presence, member/user public summaries,
repository/seed records, and delegated device presence.

For mobile/tablet devices, the DHT advertises delegated presence:

```text
device_uuid -> reachable_via node_uuid
```

It must not advertise that the physical mobile device is directly online when it
is offline or sleeping.

The home/main node is responsible for refreshing delegated presence, queueing
messages, and resuming device sessions.

## User And Member Doctrine

Node identity is separate from user identity and member identity.

Users live under:

```text
QNE/users/<user-uuid>
```

User state includes private user persist, status, UI state, and policy. QNE
Community Members additionally have a seed-assigned member ID/qnename.

User homes must not contain private downloaded skill copies. Shared QNENodeSkill
packages live under the node repository and are gated by policy.

A QNEMobileShadow may serve a user/member, but it is not stored under that
user/member. It remains a node-level device mediator.

## Master Node Doctrine

The network master is the public control-plane authority for the network.

The master is responsible for network manifest authority, system node registry,
seed/repository monitoring, governance records, master-authorized testnet
operations, observing heartbeats from system nodes, publishing required network
state, and coordinating trusted rollout policy.

The master is not a general user login server, a global owner of all private
user state, a mobile runtime, a UI host by default, or a replacement for
node-owned identity.

The master may activate network test QNENodeSkills against chosen nodes. Normal
base nodes do not run master test batches unless authorized.

## Seed Node Doctrine

A seed is a normal QNE node running the seed role/QNENodeSkill.

A seed provides first network contact, node presence registry, repository-node
hints, available QNENodeSkill index hints, DHT bootstrap, seed-side enrollment
decisions where required, and delegated DHT record acceptance under policy.

The initial network uses one permanent master seed. Replica seeds may be added
later for availability and geography, but the authority model remains one master
seed unless explicitly revised.

Permanent cloud seeds use IPv6 UDP for QNE network communication.

## Repository Node Doctrine

A repository node provides trusted QNENodeSkill package discovery and
distribution.

Public qne.info downloads are for platform installers and bootstrap artifacts.
Runtime QNENodeSkill distribution should come from QNE repository nodes or
seeds.

Repository nodes publish available package indexes. Nodes cache the available
index and apply policy before enabling or installing any QNENodeSkill.

Base node updates remain trusted node updates, not arbitrary network plugin
replacement.

## Network Startup Doctrine

A new node startup follows this order:

1. Create or restore the QNE home and keep area.
2. Validate the full filesystem layout.
3. Load or create node UUID.
4. Load or create the QNE P2P static key under persist/secrets.
5. Read node config and network manifest.
6. Prefer known same-network LAN peers if available.
7. Fall back to configured seeds.
8. Bind QNE P2P UDP.
9. Start bundled QNENodeSkills through lifecycle start/restore.
10. Advertise node presence to the seed if policy allows.
11. Receive repository/available-skill hints.
12. Start optional role QNENodeSkills: seed, repository, mobile shadow, user hosting, DHT, UI bridge.
13. Resume queued QNEMobileShadow sessions and delegated presence.
14. Enter service loop.

Shutdown follows the reverse doctrine:

1. Stop accepting new local work.
2. Send best-effort presence leave where appropriate.
3. Ask each QNENodeSkill to shutdown gracefully.
4. Pack QNENodeSkill state.
5. Persist lifecycle markers.
6. Preserve node identity, secrets, peer cache, users, shadows, and repository state.
7. Stop the service cleanly.

## Transport Doctrine

QNE node-to-node communication remains UDP-only through QNE P2P.

Transport does not define application semantics. QNENodeSkill IDs, action IDs,
topics, and payloads define behavior.

QNE P2P may keep sessions open without constant heartbeat traffic. Mobile apps
should still be treated as intermittent clients because OS battery policy,
sleep, and network changes make durable mobile participation unreliable.

## Installer And Upgrade Doctrine

Desktop/laptop installs receive the QNE node installer. Mobile/tablet installs
receive native apps.

Installers should eventually inspect the device and enable appropriate roles:

- desktop/laptop: capable node, possible DHT, user hosting, UI, repository cache
- old laptop/VM: capable node with adjustable resource use
- server/cloud: seed, repository, master, DHT
- mobile/tablet: thin native client only

Runtime upgrades must preserve:

- QNE/qnenode/persist
- persist/secrets
- persist/lmdb
- persist/ltr
- node UUID
- QNE P2P static key
- users
- QNEMobileShadow records
- peer cache
- rollback material

The base node is stopped for update and restarted after install.

## First Implementation Direction

The next code version should create qne-node-v00505 from qne-node-v00504.

Implementation priorities:

- Rename QneNodeSkill to QNENodeSkill directly.
- Add QNESceneData.
- Add bundled QNEMobileShadow as a QNENodeSkill.
- Add Android-first QNEMobileAdapter protocol shape.
- Add manual device allowlist CLI.
- Add delegated DHT presence record shape.
- Add lifecycle tests for shadow start, shutdown, restore, revocation, queued scenes, and delegated presence.

This doctrine is the source of truth for the next architecture slice.
