Roles & Scheduling Policy

For host tool usage, interdependencies, and policy/mount details, see HOST_TOOLS.md.

1. Roles

| Role | Capabilities | Namespace | |——|————–|———–| | Queen | Hive-wide orchestrator driven by cohsh: spawn/kill workers, bind/mount namespaces, inspect logs, request GPU leases across many worker instances | Full /, /queen, /shard/*/worker/* (canonical), legacy /worker/* when enabled, /log, /gpu/* (when installed), plus /policy + /actions and /audit + /replay when enabled | | WorkerHeartbeat | Minimal worker that emits heartbeat telemetry and confirms console/attach paths; many instances may run concurrently under the Queen | /proc/boot, /shard/<label>/worker/<id>/telemetry, /log/queen.log (RO); legacy /worker/<id>/telemetry when enabled | | WorkerGpu | GPU-centric worker that reads ticket/lease state and reports telemetry for host-provided GPU nodes; treated as another worker type under the Queen | WorkerHeartbeat view + /gpu/<id>/* |

Exactly one Queen exists per hive, but many worker instances (across worker-heart, worker-gpu, and future types) can be orchestrated simultaneously. The queen session attached via cohsh is the canonical path for operators and automation to exercise these roles.

Worker Namespace Sharding

• Canonical worker path: /shard/<label>/worker/<id>/telemetry.
• label is derived from sha256(worker_id)[0..=shard_bits) (top shard_bits of the first byte), formatted as two hex digits.
• sharding.legacy_worker_alias = true enables legacy /worker/<id>/telemetry aliases that resolve to the canonical shard path.
• Alias-disabled manifests must not reference /worker/* in mounts or policy rules; coh-rtc rejects them deterministically.
• Sharding requires secure9p.walk_depth >= 5 (canonical path depth). Example compiler error: sharding.enabled requires secure9p.walk_depth >= 5.
• Legacy aliases require secure9p.walk_depth >= 3. Example compiler error: sharding.legacy_worker_alias requires secure9p.walk_depth >= 3.

2. Ticket Lifecycle

1. Queen requests spawn with desired role/budget.
2. Root task allocates capability space, minting a Ticket bound to the role, worker identity (subject), and mount table.
3. Ticket is delivered during 9P attach; NineDoor verifies MAC and initialises session state.
4. On kill or budget expiry, root task revokes ticket and notifies NineDoor to clunk all active fids.

Attachments always arrive via NineDoor: queen mounts the full namespace, worker-heartbeat mounts only its telemetry and boot views, and worker-gpu attaches to the /gpu/<id>/ subtrees exposed to its ticket. Ticket values (when present) select the role-specific namespace, and NineDoor aborts attaches on ticket mismatch, timeouts, or unsupported roles, leaving cohsh detached with an explicit error.

3. Policy and Control Surfaces (Milestones 21a-24c)

Role orchestration is file-oriented: control actions are append-only writes to control files that the queen drives through cohsh or host tools. There is no ad-hoc RPC path.

Policy gating and approvals

• Policy gating is manifest-enabled. When active, /policy and /actions namespaces appear.
• /policy/rules is the manifest-derived snapshot of gate targets.
• /actions/queue is the approval/denial log. Each approval includes id, target, and decision.
• If a control write targets a gated path (for example /queen/ctl), the write is denied with ERR ECHO reason=policy ... EPERM until a matching approval is queued.
• Approvals are consumed deterministically when accepted, and may be audited when /audit is enabled.

Control files and observability

• Scheduling control: /queen/schedule/ctl (append-only JSONL commands).
• Lease control: /queen/lease/ctl (append-only JSONL commands).
• Export control: /queen/export/ctl (append-only JSONL commands).
• Policy control: /policy/ctl (apply/rollback JSONL commands).
• Scheduling observability: /proc/schedule/summary, /proc/schedule/queue.
• Lease observability: /proc/lease/summary, /proc/lease/active, /proc/lease/preemptions.
• Policy observability: /policy/preflight/* and /proc/pressure/policy.

These paths are manifest-gated and bounded. If a namespace is missing, check the manifest settings and whether the host-side publishers (for /gpu or /host) are running.

4. Scheduling Strategy

• v0: Round-robin over runnable endpoints with per-worker tick budgets (coarse-grained cooperative scheduling).
• v1: Priority bands (system, control, worker) with budgeted quanta; queen/control tasks reside in higher band.
• GPU (future): Lease-enforced concurrency; GPU workers must honour host-provided stream counts.

Control flows are file-oriented (e.g., appends to /queen/ctl) instead of the deprecated RPC/virtual-console sketches; cohsh always runs outside the Cohesix instance—QEMU during development and UEFI hardware in deployment—and speaks the NineDoor transport.

Scheduling contexts originate in root-task: initial SCs are held by root, carved out for NineDoor and per-worker threads, and reclaimed on revocation without altering seL4 SC semantics or time accounting.

5. Budget Types

pub struct Budget {
    pub ticks: Option<u32>,     // scheduler quanta
    pub ops: Option<u32>,       // NineDoor operations
    pub ttl_s: Option<u32>,     // wall-clock lifetime
}

• Budgets default to conservative limits; queen can request overrides but root task may clamp to policy maximums.
• NineDoor decrements ops budgets per successful request; when depleted it signals root task for revocation.

6. Revocation Flow

1. Budget exhaustion detected by NineDoor or root task watchdog.
2. Root task sends Revoke(ticket_id) to NineDoor.
3. NineDoor marks session closed, replies Rerror(Closed) on further operations, and appends revocation reason to /log/queen.log.
4. Root task deallocates resources (TCB caps, scheduling context).

7. Testing Expectations

• Unit: Role-path filter tests ensure workers cannot traverse outside assigned mounts. Budget counters validated with deterministic scenarios.
• Integration: Scenario test spawns two heartbeat workers with different TTLs; verifies early expiry worker is revoked and log entry recorded.
• Fuzz: Randomised spawn/kill command sequences ensure scheduler state remains consistent (no leaked caps).

Cross-refs: see SECURE9P.md for namespace enforcement, USERLAND_AND_CLI.md for attach semantics, ARCHITECTURE.md for console and control path semantics, and HOST_TOOLS.md for operator-facing workflows.

8. Future Extensions

• Role hierarchy for observers/auditors.
• Quotas for memory/IPC buffers enforced via seL4 resource allocation APIs.
• Worker-side cooperative yields signalled via /shard/<label>/worker/<id>/yield (legacy /worker/<id>/yield when enabled).