⚠️ Historical design document. This predates the implementation and describes original intent, not the shipped system. For the as-built architecture see the Architecture Decision Records and the CHANGELOG; where they disagree with this file, they are correct.

User-Space Services Architecture

Service Design Principles

Core Service Philosophy

1. Minimal Kernel, Maximum User Space - Everything possible lives in user space
2. Capability-Based Communication - Services communicate via IPC with capabilities
3. Fault Isolation - Service crashes don't affect kernel or other services
4. Pluggable Architecture - Services can be replaced or upgraded independently
5. Quantum-Aware Design - Services understand quantum resource constraints

Service Categories

1. Quantum Scheduler Service

Purpose: Optimize quantum resource allocation and scheduling

// Quantum scheduler API messages
typedef enum {
    QUANTUM_SCHED_ALLOCATE = 1,
    QUANTUM_SCHED_RELEASE,
    QUANTUM_SCHED_SCHEDULE,
    QUANTUM_SCHED_STATUS,
    QUANTUM_SCHED_POLICY_SET
} quantum_sched_msg_t;

typedef struct {
    quantum_sched_msg_t type;
    uint32_t process_id;
    uint32_t qubits_required;
    uint64_t coherence_deadline;
    uint32_t priority;
    uint32_t policy;
} quantum_sched_request_t;

typedef struct {
    quantum_sched_msg_t type;
    uint32_t status;
    uint32_t *allocated_qubits;
    uint32_t num_qubits;
    uint64_t estimated_completion;
} quantum_sched_response_t;

Key Features:

• Multiple scheduling policies (FIFO, coherence-aware, energy-minimizing)
• Real-time coherence window management
• Quantum circuit batching and optimization
• Integration with classical scheduler

2. Memory & Entropy Manager Service

Purpose: Manage classical memory and quantum entropy resources

// Memory manager API
typedef enum {
    MEM_ALLOCATE = 1,
    MEM_RELEASE,
    MEM_SHARE,
    MEM_PROTECT,
    ENTROPY_GET,
    ENTROPY_REFRESH
} memory_msg_t;

typedef struct {
    memory_msg_t type;
    uint32_t process_id;
    size_t size;
    uint32_t permissions;
    uint32_t memory_type;  // CLASSICAL, ASSOCIATIVE, QUANTUM
} memory_request_t;

typedef struct {
    memory_msg_t type;
    uint32_t status;
    void *address;
    uint64_t entropy_available;
    uint32_t entropy_quality;
} memory_response_t;

Key Features:

• Classical memory allocation with NUMA awareness
• Associative memory for cognitive operations
• Entropy pool management (thermal, quantum, algorithmic)
• Memory pressure monitoring and reclamation

3. Device Manager Service

Purpose: Abstract hardware devices and provide unified interfaces

// Device manager API
typedef enum {
    DEVICE_ENUMERATE = 1,
    DEVICE_OPEN,
    DEVICE_CLOSE,
    DEVICE_IOCTL,
    DEVICE_READ,
    DEVICE_WRITE,
    DEVICE_INTERRUPT_REGISTER
} device_msg_t;

typedef struct {
    device_msg_t type;
    uint32_t device_type;
    uint32_t device_id;
    uint32_t operation;
    void *data;
    size_t data_size;
} device_request_t;

typedef struct {
    device_msg_t type;
    uint32_t status;
    uint32_t device_count;
    device_info_t *devices;
    void *result_data;
    size_t result_size;
} device_response_t;

Key Features:

• Device enumeration and capability detection
• Unified device I/O interface
• Interrupt routing to user-space handlers
• Power management integration

4. Filesystem Service

Purpose: Provide storage abstraction for different storage types

// Filesystem API
typedef enum {
    FS_MOUNT = 1,
    FS_UNMOUNT,
    FS_OPEN,
    FS_CLOSE,
    FS_READ,
    FS_WRITE,
    FS_CREATE,
    FS_DELETE,
    FS_STAT
} fs_msg_t;

typedef struct {
    fs_msg_t type;
    char path[256];
    uint32_t flags;
    uint32_t mode;
    void *data;
    size_t size;
} fs_request_t;

typedef struct {
    fs_msg_t type;
    uint32_t status;
    uint32_t fd;
    size_t bytes_transferred;
    fs_stat_t stat_info;
} fs_response_t;

Key Features:

• Multiple filesystem types (classical, object, quantum result archives)
• Deterministic and probabilistic snapshot support
• Distributed storage integration
• Versioning and provenance tracking

Service Architecture

Service Lifecycle

// Service control structure
typedef struct {
    uint32_t service_id;
    char name[64];
    uint32_t pid;
    uint32_t state;  // STARTING, RUNNING, STOPPING, CRASHED
    uint32_t capabilities;
    uint64_t start_time;
    uint32_t restart_count;
    uint32_t max_restarts;
} service_info_t;

// Service states
#define SERVICE_STARTING   0
#define SERVICE_RUNNING    1
#define SERVICE_STOPPING   2
#define SERVICE_CRASHED    3
#define SERVICE_STOPPED    4

Service Manager

// Service manager API
typedef enum {
    SVC_START = 1,
    SVC_STOP,
    SVC_RESTART,
    SVC_STATUS,
    SVC_LIST,
    SVC_MONITOR
} service_msg_t;

typedef struct {
    service_msg_t type;
    char service_name[64];
    uint32_t priority;
    char args[256];
} service_request_t;

typedef struct {
    service_msg_t type;
    uint32_t status;
    service_info_t service_info;
    uint32_t service_count;
    service_info_t *services;
} service_response_t;

Service Communication

IPC Message Format

// Standard service message header
typedef struct {
    uint32_t source_service;
    uint32_t dest_service;
    uint32_t message_type;
    uint32_t message_id;
    uint64_t timestamp;
    uint32_t capability_id;  // Authorization
    uint32_t priority;
} service_msg_header_t;

// Complete service message
typedef struct {
    service_msg_header_t header;
    size_t payload_size;
    uint8_t payload[4096];  // Configurable max size
} service_message_t;

Service Discovery

// Service registry
typedef struct {
    char name[64];
    uint32_t service_id;
    uint32_t version;
    uint32_t capabilities;
    char interface_hash[64];  // API version hash
    uint32_t pid;
    uint64_t last_heartbeat;
} service_registry_entry_t;

// Discovery API
typedef enum {
    SVC_DISC_REGISTER = 1,
    SVC_DISC_UNREGISTER,
    SVC_DISC_LOOKUP,
    SVC_DISC_LIST,
    SVC_DISC_HEARTBEAT
} discovery_msg_t;

Service Implementation Structure

Service Template

services/
├── service-template/
│   ├── service.c           # Main service loop
│   ├── api.c              # API message handlers
│   ├── handlers.c          # Business logic
│   ├── protocol.h          # Message definitions
│   └── Makefile

Quantum Scheduler Service

services/quantum-scheduler/
├── main.c                 # Service entry point
├── scheduler.c            # Scheduling algorithms
├── policies/
│   ├── fifo.c            # FIFO scheduling
│   ├── coherence.c       # Coherence-aware scheduling
│   ├── energy.c          # Energy-minimizing scheduling
│   └── error_rate.c      # Error-rate minimizing
├── quantum_api.c          # Quantum resource interface
├── monitoring.c           # Performance monitoring
├── protocol/
│   ├── messages.h         # Message definitions
│   └── client_api.h       # Client library API
└── tests/
    ├── unit_tests.c
    └── integration_tests.c

Memory Manager Service

services/memory-manager/
├── main.c
├── classical_mem.c        # Classical memory management
├── associative_mem.c      # Associative memory interface
├── entropy_manager.c      # Entropy pool management
├── numa_aware.c          # NUMA optimization
├── pressure_monitor.c     # Memory pressure detection
├── protocol/
│   ├── messages.h
│   └── client_api.h
└── tests/

Device Manager Service

services/device-manager/
├── main.c
├── device_enumeration.c   # Device discovery
├── device_io.c           # I/O operations
├── interrupt_router.c     # Interrupt handling
├── power_manager.c        # Power management
├── drivers/              # Device drivers
│   ├── quantum/
│   ├── classical/
│   └── neuromorphic/
├── protocol/
│   ├── messages.h
│   └── client_api.h
└── tests/

Service Security

Capability-Based Access

// Service capability structure
typedef struct {
    uint32_t service_id;
    uint32_t client_id;
    uint32_t allowed_operations;
    uint32_t resource_limits;
    uint64_t expiration;
} service_capability_t;

// Capability checking
bool service_check_capability(const service_capability_t *cap, uint32_t operation);
bool service_check_resource_limit(const service_capability_t *cap, uint32_t resource);

Service Isolation

• Separate Address Spaces: Each service runs in isolated memory
• Limited Capabilities: Services only get capabilities they need
• Intent Manifest + Resource Limits (epic #135): each service carries a per-pid intent manifest — the allow-set built from its grant flags, bound in the same interrupt-off window that mints its caps and checked at every capability-gated syscall. The spawn_max quota is the first ENFORCED resource limit: it caps successful SYS_SPAWNs per incarnation (checked before side effects, charged on success, refusal recorded as AUDIT_QUOTA). A service's cpu_limit is the second enforced limit (epic #144): once a citizen's scheduled-in cpu_ticks exceed it, the kernel terminates it from the timer tick (recording AUDIT_CPUKILL), so a busy-spin runaway cannot hog the CPU. cpu_limit is opt-in (0 = unlimited); a service that sets it may NOT be service_monitor'd (the kernel refuses — a watchdog respawn would reset the budget and re-kill it forever). HONEST STATUS: the memory_limit / quantum_limit fields in service_config_t below are still NOT enforced — a runtime memory quota in particular is vacuous (page faults kill; there is no runtime per-process allocation to meter). spawn_max and cpu_limit are the enforced ones today.
• Audit + Manifest Logging: capability GRANT/DENY/SPAWN plus manifest MDENY (a held cap exceeding declared intent) and QUOTA denials are recorded in the kernel authority ledger (SYS_AUDIT); declared intent is readable via SYS_MANIFEST.
• Capability Delegation (epic #137): a service may set grant_field_delegable alongside grant_field to mint its field cap with CAP_GRANT, making it the (sole, auditable) DELEGATOR — at runtime it may SYS_CAP_DERIVE a strictly-narrowed slice of that region to a sub-agent it is wired to over IPC. The derive is bounded by the delegator's own manifest and extends the recipient's manifest (manifest_grant), is one-hop (CAP_GRANT/CAP_REVOKE never handed over), and cascade-revokes when the delegator dies. service_pid_is_monitored lets the kernel refuse delegating to a monitored service (whose restart would rebind its manifest and drop the delegated row). Proven by the delegation-test → subagentd boot demo.

Service Monitoring

Health Monitoring

// Service health metrics
typedef struct {
    uint32_t service_id;
    uint64_t uptime;
    uint32_t message_count;
    uint32_t error_count;
    double cpu_usage;
    size_t memory_usage;
    uint32_t quantum_resources_used;
    uint64_t last_message_time;
} service_health_t;

// Monitoring API
typedef enum {
    MONITOR_HEALTH = 1,
    MONITOR_METRICS,
    MONITOR_LOGS,
    MONITOR_ALERTS
} monitor_msg_t;

The health-monitor thread scans monitored services and, when one misses its heartbeat, service_restarts it up to max_restarts times. On the give-up edge — the budget is exhausted — it must still service_stop the offender. A service that merely crashed is already TERMINATED and gets reaped, but a hung one (alive yet silent — the exact condition the watchdog exists to catch) would otherwise be left RUNNING forever: never re-scanned (state ≠ RUNNING), never reaped (not TERMINATED), never stopped, holding its PCB slot and a scheduler slice. So the restart-limit branch reclaims the process (via the generation-guarded, idempotent service_stop) rather than abandoning it. The service self-test drives a max_restarts=1 service to give-up and asserts the process is destroyed, gating on `SVCGIVEUP: restart budget exhausted reclaims the process`.

Performance Metrics

• Message Latency: Time from request to response
• Throughput: Messages per second
• Resource Utilization: CPU, memory, quantum resources
• Error Rates: Failed operations and service crashes
• Availability: Service uptime and restart frequency

Service Configuration

Configuration Management

// Service configuration
typedef struct {
    char service_name[64];
    uint32_t version;
    uint32_t priority;
    uint32_t cpu_limit;
    size_t memory_limit;
    uint32_t quantum_limit;
    char startup_args[256];
    char dependencies[8][64];  // Required services
    uint32_t restart_policy;   // NEVER, ON_FAILURE, ALWAYS
} service_config_t;

Dynamic Configuration

• Runtime Reconfiguration: Services can be reconfigured without restart
• Policy Updates: Scheduling policies can be updated dynamically
• Resource Adjustment: Limits can be adjusted based on load
• Feature Flags: Features can be enabled/disabled per service

Success Criteria

• All services communicate via IPC with capabilities
• Service isolation prevents cascading failures
• Quantum scheduler optimizes resource utilization
• Memory manager handles all memory types efficiently
• Device manager abstracts hardware complexity
• Services can be updated independently
• Monitoring provides comprehensive visibility
• Configuration system supports dynamic updates

Performance Targets

• Service Startup: < 100ms for essential services
• IPC Latency: < 50 microseconds between services
• Quantum Scheduling: < 10 microseconds allocation time
• Memory Allocation: < 5 microseconds for small allocations
• Device I/O: < 1 millisecond for standard operations

This user-space services architecture provides the flexibility and isolation needed for a robust quantum-aware operating system while maintaining the microkernel philosophy.