Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Capability-Infrastructure Cluster Backlog

A planning audit found a cluster of maturing proposals whose Phase 1 slices are now extractable (their stated prerequisites have landed) plus the Stage 6 capability remainder. Most of these slices ADD interfaces to schema/capos.capnp and therefore share the schema serial surface: only one plan at a time may change the schema (docs/backlog/index.md “Concurrency Notes”), and the next plan must rebase on the generated-code refresh. This file decomposes the cluster and records the recommended ordering so the slices do not all become ready at once and collide on that surface.

Loopyard tasks point here for the cluster; it should not inline the details.

Ordering Contract

  • The non-schema slices (capos-service framework, tickless idle, default avatar) are dispatchable in parallel today and have their own ready task files; they do NOT queue here.
  • The schema-touching slices below queue on the shared schema serial surface. Promote ONE at a time from this backlog into a loopyard task, land it, refresh generated bindings, then promote the next. Do not file all of them as ready simultaneously.
  • The ResourceProfileRecord / ManifestResourceProfile schema, capos_config::ResourceProfile carrier, and non-schema spawn-limit enforcement have landed. Crypto key caps Phase 1, debug-session-phase1, and crash-recovery-stale-cap-phase1 have also landed. The next queued schema-serial slice is authority-broker-phase1.
  • Recommended schema promotion order from here: authority-broker → live-upgrade CapRetarget → Stage 6 remainder. Reorder by explicit user priority. Do not promote a schema slice in parallel with another schema-surface task.

Schema-Serial Phase-1 Slices

Each slice names a 1-line scope, the owning proposal, and the conflict domains its eventual task file should carry. All share interface:schema-capos-capnp + path:schema/capos.capnp + path:tools/generated/ (the serial surface) in addition to the listed domains.

monitoring-log-surface (landed)

  • Scope: LogSink/LogReader schema + a minimal userspace log service backed by Console, with logLevel enforcement and scoped LogSink caps granted to children at spawn. Source: docs/proposals/system-monitoring-proposal.md.
  • Domains: resource:system-monitoring, path:kernel/src/cap/, path:demos/, docs:system-monitoring.
  • Landed (2026-05-25): additive LogSink.write @38 / LogReader.read @39 plus LogRecord/LogFilter (reusing LogLevel), backed by a bounded drop-oldest kernel ring (kernel/src/cap/log.rs). The sink drops below- SystemConfig.logLevel records (boot-seeded) and forwards accepted records to serial; the reader returns cursor/filtered records with nextCursor/dropped. capos-rt LogSinkClient/LogReaderClient, producer/reader demos, system-monitoring-log.cue, and make run-monitoring-log-smoke prove the sink drop, read-back, and reader-side minLevel filter. The wider Severity (critical), correlation fields, token-bucket backpressure, and persistent retention remain later phases. Task: cap-infra-monitoring-log-surface.
  • Operator read side (2026-07-16): the capos-shell log builtin reads the retained ring through a granted read-only log (LogReader) cap, printing a bounded records=/dropped= window plus one line per record. It is a read-only consumer: the shell holds no LogSink. Absence of the grant is fail-soft, matching uptime/ls. make run-shell-log boots system-shell-log.cue (producer service fills the ring, shell reads it back) and system-shell-log-ungranted.cue (same producer, no grant), proving the fail-soft path is about the missing cap rather than an empty ring. The log man page is deferred to the manual-pages slice.

crypto-key-caps-phase1 (landed)

  • Scope: SymmetricKey/PrivateKey/PublicKey schema interfaces + a software-backed userspace key service + a QEMU encrypt/sign smoke over the cap boundary. Unblocks TLS, OIDC, volume encryption, signed audit, SSH cert upgrade. Source: docs/proposals/cryptography-and-key-management-proposal.md.
  • Domains: resource:crypto-key-service, path:demos/, docs:cryptography-and-key-management.
  • Landed (2026-06-06): minimal RAM-only SymmetricKey, PrivateKey, and PublicKey ABI in schema/capos.capnp, regenerated bindings, capos-tls XChaCha20+HMAC-SHA256/P-256 cores, RAM KeyVault private-key custody, and the development-only KeySource bootstrap. Local proofs cover symmetric AEAD/MAC, private/public signing, KeyVault stale-handle custody, and development-source admission/rejection. Remaining work is production/runtime key service wiring, symmetric derivation/wrapping, persistence, hardware/cloud custody, ACME/TLS handshakes, and production public-ingress key sources. Task: cap-infra-crypto-key-caps-phase1-reconcile-local-proof.

time-wallclock-phase1 (landed)

  • Scope: WallClock read cap + ClockProvenance label + manifest-seeded boot time; WASI clock_time_get(REALTIME) and audit timestamp delegate to it. Source: docs/proposals/time-and-clock-proposal.md.
  • Domains: resource:time-clock-authority, path:kernel/src/cap/, docs:time-and-clock.
  • Landed (2026-05-24, fixed-boot-base variant): WallClock.wallTime read cap + ClockProvenance enum (untrusted @0 fail-closed zero value), KernelCapSource::wallClock @36, kernel/src/cap/wall_clock.rs, the capos-rt WallClockClient, and a shell date command granted wall_clock in system-shell.cue and asserted by make run-shell. Manifest seedUtcSeconds, a stateful WallClockState, WASI realtime-clock delegation, and init audit/TLS grants remain Phase 1.x / Phase 2 follow-ups. Task: time-wallclock-phase1.

crash-recovery-stale-cap-phase1 (landed)

  • Scope: stale-cap DISCONNECTED/server-death CQE propagation to in-flight callers and endpoint holders on unplanned process death, plus a redacted CrashRecord appended to AuditLog. Source: docs/proposals/crash-recovery-supervision-proposal.md.
  • Domains: resource:crash-recovery, path:kernel/src/cap/, path:kernel/src/process.rs, docs:crash-recovery.
  • Landed (2026-07-16), closing the “is my server gone?” half of the scope only. The premise that in-flight callers got no completion was wrong – Process::release_caps_for_exit already canceled endpoint state and posted a CQE. The real gap was that the cancel carried the generic CAP_ERR_INVOKE_FAILED (-4), indistinguishable from many unrelated failures. This slice adds the additive CAP_ERR_SERVER_DIED (-11), posted only for cancels caused by the endpoint owner’s process teardown; every other cancel path (owner RELEASE, thread exit while the process lives, revoke) keeps -4 unchanged. The additive CrashKind / CrashRecord schema landed, and unplanned deaths now emit a redacted kernel-internal [audit] event=crash record after cap revocation. make run-crash-disconnect proves a queued and an in-flight call both complete with -11 when the endpoint-owning server dies by fault.
  • Explicitly NOT closed by this slice, despite “(landed)”: the “did it crash or terminate cleanly?” half. The CQE deliberately does not distinguish the two, and the crash record that does is emitted only to the kernel audit log, which no supervisor can read – so no supervisor can yet tell a crash from a planned termination. That needs Phase 2 delivery of CrashRecord to the supervisor’s AuditLog cap. Also deferred: CrashKind::panic (the capos-rt panic handler exits via the planned exit syscall, so it is never emitted), lastSqeOpcode (always 0), and an SMP residual where concurrent thread exits in a multithreaded process can report an in-flight call as -4. All are detailed in the proposal.
  • Deviation: the record is not delivered as the proposal’s literal CapException { disconnected } in the caller’s result buffer; see the proposal’s Stale-Cap Propagation section for why.

debug-session-phase1 (landed)

  • Scope: DebugSession attach cap (owner-consent or broker maintenance grant, audited) + read-only cap-table snapshot that transfers no authority. Source: docs/proposals/debug-trace-authority-proposal.md.
  • Domains: resource:debug-trace-authority, path:kernel/src/cap/, docs:debug-trace.
  • Landed: kernel/src/cap/debug_session.rs mints a read-only redacted cap-table snapshot via ProcessHandle.createDebugSession under owner consent, audited, fail-closed on an exited target, transferring no invokable cap. Proof make run-debug-session.

authority-broker-phase1

  • Scope: endpoint-served AuthorityBroker + ShutdownControl schema + runtime client + a QEMU proof that an anonymous shell cannot invoke shutdown. Source: docs/proposals/userspace-authority-broker-proposal.md.
  • Domains: resource:authority-broker, path:init/, path:shell/, docs:userspace-authority-broker.
  • Status note: the interim kernel broker no longer owns hard-coded demo binary allowlists. kernelParams.authorityBrokerPolicy now carries the admitted session-context, remote-client spawn, and worker service grant policy with manifest validation.
  • DONE (2026-07-17): endpoint-served UserspaceAuthorityBroker + ShutdownControl, proof make run-userspace-authority-broker. Phase 1 was briefly on hold because a userspace broker could not return ShutdownControl as a result cap: a manifest {service: ...} endpoint facet is CapTransferMode::NonTransferable, while copy-transfer requires Copy. The endpoint-facet-redelegation-transfer-path task resolved that by adding the delegableClientEndpoint grant mode, so the broker’s shutdown cap is granted delegable: true and copy-transfers to admitted callers. The other half of the hold, an unresolvable sessionCapId, was settled by binding the requested profile to the badge init stamps on the caller’s facet – the one caller property the kernel reports unforgeably – mirroring the kernel broker’s UserSession check. Denials are audited (event=broker result=denied), so the userspace successor does not regress the kernel broker’s visibility. Written up in docs/proposals/userspace-authority-broker-proposal.md.
  • Scope landed is the broker’s authority model and denial rule, proven against purpose-built manifest-badged demo processes. The interactive shell is not yet a client of this broker; making the denial true of the shipped shell is Phase 2/3 work. Phase 2 (init-owned shutdown) and Phase 3 (serviceEndpoints) remain queued.

live-upgrade-capretarget-phase1 (done)

  • Scope: ProcessControl + retargetCaps kernel op for stateless Case 1 upgrades, with a QEMU retarget-mid-call smoke. Foundation for DDF userspace-driver fault containment. Source: docs/proposals/live-upgrade-proposal.md.
  • Domains: resource:live-upgrade, path:kernel/src/cap/, docs:live-upgrade.
  • Landed: ProcessControl.retargetCaps (kernel/src/cap/process_control.rs, processControl @52) moves endpoint-owner slots between generation-bound ProcessHandle targets, all-or-nothing and audited. make run-cap-retarget proves one client CapId answered by v1 and then by v2, inheriting the call queued across the move with no disconnect, and a graceful retarget refused while v1 holds a call in flight.
  • Follow-up left for Phase 2: the successor cannot discover the slot moved into it (no self-introspection of a process’s own cap table), so the supervisor must diff its table and name the CapId over a side channel. Belongs with the Upgradable.resume contract; recorded in the proposal.

system-info-hostname (done)

  • Scope: add hostname to the SystemInfo cap + kernelParams.hostname + manifest field. Source: docs/proposals/system-info-proposal.md Phase 3.
  • Domains: resource:system-info, path:kernel/src/cap/, docs:system-info.
  • Landed: SystemInfo.hostname @1 served from kernelParams.hostname (default capos), printed by the shell hostname command, asserted in run-shell. Task: cap-infra-system-info-hostname.

stage6-remainder

  • Scope: the remaining Stage 6 capability semantics – SharedBuffer SQE opcode + kernel mapping authority and typed notification objects with ring Recv integration. Decomposed in docs/backlog/stage-6-capability-semantics.md; queue each as its own slice on the schema surface. Source: roadmap Stage 6.
  • Domains: resource:stage6-capability-semantics, path:kernel/src/cap/, path:kernel/src/cap/ring.rs, docs:stage-6.
  • Landed sub-slice (2026-07-18 13:39 UTC): CapabilityManager.list/revoke plus manager-mediated grant(sourceCapId) -> targetCapId. Grant copies only a live copy-transferable caller hold into the manager’s generation-bound child, applies session scope and target quotas, preserves one-way source-revocation propagation without giving child revocation authority over the source, and emits ordered cap_grant audit outcomes. Proof: make test-capability-manager-grant; list regression: make run-debug-session.

Non-Schema Slices

These are dispatchable now and are tracked as ready or done tasks, not queued on the schema serial surface:

  • Done: cap-infra-resource-profile-enforcement-local-proof – binds the existing ResourceProfileRecord / ManifestResourceProfile and capos_config::ResourceProfile carrier to remaining cap-slot and thread spawn-limit enforcement, with rollback proof (cap-infra-resource-profile-enforcement-local-proof).
  • Done: capos-service-lifecycle-slice1 – ServiceMain/lifecycle framework above capos-rt, one converted gateway proof (capos-service-lifecycle-slice1).
  • Done: default-user-avatar – deterministic native-shell avatar selection over the shipped flat catalog, printed in the shell session output without schema or broker changes (default-user-avatar).
  • Done: scheduler-tickless-idle-step6 – enable true-idle tickless windows while keeping cap-enter polling dependencies periodic (scheduler-tickless-idle-step6).

Still-Gated (not in this cluster)

Memory-authority, OOM/swap, certificates/TLS, OIDC, volume-encryption, go-runtime, chat-multimedia, llm/agent, browser, GPU, formal-MAC/MIC, cloud-metadata, HPC, scientific, hosted-agent-swarm remain gated on this cluster, DDF, networking, storage persistence, or SMP Phase C / Ring v2. See each proposal’s gating note and docs/backlog/research-design-gaps.md.