Architecture Overview

Vinxi Kernel Architecture Notes

Namespace

vinxi-* is the base platform namespace. Lepton products such as NetworkAccess, Trafficure, SmartMarket, and SmartBuild sit above Vinxi.

Verbs

All userland, control-plane, drivers, agents, and services interact with kernel-owned reality through the six verbs:

Verb	Meaning
Query	Read through policy/queryability gates
Act	Request an internal state transition/decision
Assert	Record observation/evidence/claim
Call	Perform external side-effect through egress gateway
Subscribe	React to changes/streams
Schedule	Time-trigger a job/workflow

Planes

Plane	Responsibility
Process	Actions, decisions, workflows, retries, call intents
Truth	Immutable logs, statements, schemas, policies, evidence
World	Resolved current interpretation of reality
Serving	Fast projections; truth of nothing
Materialization	Pipelines, jobs, transforms, indexes, rebuild machinery

Ports and adapters

Ports are kernel-owned contracts. Adapters are implementation choices.

vinxi-kernel-core may depend on:

vinxi-port-state
vinxi-port-log
vinxi-port-blob
vinxi-port-world

It must not depend on:

sqlx
postgres vendor SDKs
minio/s3 vendor SDKs
external SaaS SDKs
device protocol clients

Driver boundary

External connectors and device drivers are not trusted database writers.

Allowed:

driver -> Assert
driver -> RegisterResourceVersion
driver -> SubmitCallResult
driver -> AdvanceCheckpoint

Forbidden:

driver -> truth.statement_log table
driver -> world.resource_status_current table
driver -> catalog.resource_version table directly
driver -> unrestricted object store credentials

First Lean profile

The initial Lean profile uses:

P1/P2/P23 metadata stores: Postgres/PostGIS
P6 blob: filesystem adapter in dev, MinIO/S3-compatible later
P7/P8 transforms: custom Rust worker first
P18 SDK: generated contracts later; handwritten server route only for bootstrap

The migration path keeps ports stable while replacing adapters.