These docs are under active development and cover the v0.20 Kobicha security model.
Peios Learn
On this page
Print Full Specification
§10.1

Startup

§10.1.1 Dependencies

eventd requires the following subsystems to be available before it can operate:

  • KMES (PSD-003) -- for event ingestion. KMES is available as soon as PKM is loaded.
  • LCS / loregd (PSD-005, PSD-006) -- for registry configuration. eventd reads all its configuration from the registry.
  • KACS (PSD-004) -- for access control. eventd uses the KACS AccessCheck API for query authorization and kacs_open_peer_token for caller identification.
  • peinit (PSD-007) -- for boot ID and service lifecycle management.

eventd is a peinit-managed service. peinit starts eventd after loregd is available (eventd cannot read its configuration without the registry).

§10.1.2 Bootstrap sequence

eventd startup proceeds in the following order:

§10.1.2.1 Phase 1: Configuration

  1. Read all configuration keys from the registry under Machine\System\eventd\. Required keys are EventStorePath, LogStorePath, MetricStorePath, QuerySocketPath, LogSocketPath, and MetricSocketPath. If any required key is missing or invalid, eventd MUST fail to start.
  2. Read optional configuration keys (StorageShards, MaxBatchSize, MaxBatchLatencyMs, LogMaxBatchSize, LogMaxBatchLatencyMs, and all other tuning parameters). Apply compiled-in defaults for missing keys.
  3. Arm a persistent watch on Machine\System\eventd\ to detect configuration changes at runtime.

§10.1.2.2 Phase 2: Storage initialization

  1. Open or create the event shard databases in the event store directory. For each shard: verify schema version, open in WAL mode with synchronous=FULL, create tables and indexes if new. Log errors for databases with unrecognised schema versions (open read-only for queries, do not write).
  2. Open or create the log store database. Verify schema, open in WAL mode with synchronous=NORMAL.
  3. Open or create the metric store database. Verify schema, open in WAL mode with synchronous=NORMAL. Load the series table into the in-memory series cache.
  4. Load adaptive indexing state: read query frequency counters from metadata, discover material indexes from each shard's schema, compute the current global desired index set.
  5. Load adaptive rollup state: read rollup query frequency counters, discover existing rollups.

§10.1.2.3 Phase 3: Boot boundary

  1. Read the current boot ID from peinit.
  2. Compare the boot ID against the most recently stored boot ID in the event shard databases.
  3. If the boot ID differs (new boot): reset all per-CPU sequence trackers to 0, record the new boot ID.
  4. If the boot ID matches (restart within same boot): read the last persisted sequence number per CPU from the event store, resume sequence tracking from those values.

§10.1.2.4 Phase 4: KMES attachment

  1. Call kmes_attach (PSD-003 syscall 1091) to obtain per-CPU ring buffer file descriptors. The caller's token MUST hold SeSecurityPrivilege.
  2. Map each per-CPU ring buffer.
  3. Compute shard-to-CPU assignments based on the configured StorageShards value and the CPU count.

§10.1.2.5 Phase 5: Socket creation

  1. Create the query socket at QuerySocketPath.
  2. Create the log ingestion socket at LogSocketPath.
  3. Create the metric ingestion socket at MetricSocketPath.
  4. Set filesystem permissions on the log and metric sockets to allow service writes.

§10.1.2.6 Phase 6: Thread startup

  1. Start one drain thread per CPU. Each drain thread begins reading from its assigned ring buffer.
  2. Start one writer thread per event shard.
  3. Start the log ingestion thread.
  4. Start the metric ingestion thread.
  5. Start the retention background thread.
  6. Start the adaptive indexing/rollup background thread.

§10.1.2.7 Phase 7: Ready

  1. Emit a synthetic eventd.startup event recording the boot ID, shard count, and per-CPU sequence resume points.
  2. Signal readiness to peinit.

§10.1.3 Failure during startup

If any phase fails, eventd MUST NOT signal readiness to peinit. eventd SHOULD log the failure and exit with a nonzero status. peinit's restart policy determines whether eventd is retried.

Partial startup is not permitted. eventd either completes the full bootstrap sequence and signals readiness, or it fails entirely. There is no degraded mode where eventd operates without one of its stores or without KMES attachment.

ⓘ Informative
The "no degraded mode" rule is a v0.23 simplification. Future versions may allow eventd to operate with partial functionality (e.g., log and metric ingestion without event ingestion if KMES is unavailable). For v0.23, the all-or-nothing model is simpler and avoids complex partial-failure state management.

§10.1.4 Configuration changes at runtime

eventd watches the configuration registry subtree for changes. When a change is detected:

  • Tuning parameters (batch sizes, latencies, retention periods, adaptive thresholds, query timeout): applied immediately to the running instance.
  • Socket paths: ignored until restart. Changing a socket path requires an eventd restart.
  • Store paths: ignored until restart. Changing a store path requires an eventd restart.
  • StorageShards: ignored until restart.

eventd MUST emit a synthetic eventd.config_change event for each configuration change applied at runtime.