From 81cf07e4b206d551e51c923d151ae14d64f73105 Mon Sep 17 00:00:00 2001 From: Haishi Bai Date: Mon, 4 May 2026 16:54:39 -0700 Subject: [PATCH] initial doc --- docs/features/veci/index.rst | 395 +++++++++++++++++++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 docs/features/veci/index.rst diff --git a/docs/features/veci/index.rst b/docs/features/veci/index.rst new file mode 100644 index 00000000000..f9340026f2c --- /dev/null +++ b/docs/features/veci/index.rst @@ -0,0 +1,395 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _veci_feature: + +VECI +#### + +.. document:: VECI + :id: doc__veci + :status: draft + :safety: QM + :security: YES + :tags: feature_request + :realizes: wp__feat_request + +.. toctree:: + :maxdepth: 1 + :glob: + :titlesonly: + :hidden: + + */index + +Feature flag +============ + +To activate this feature, use the following feature flag: + +``experimental_veci`` + +Abstract +======== + +This proposal introduces the Vehicle External Control Interface (VECI), a standardized vehicle-side interface layer +for interaction with external management systems such as cloud or on-premises orchestrators. VECI enables vehicles to +expose selected runtime state, accept externally requested target state, and reconcile desired state under local +validation and enforcement. + +VECI defines an end-to-end interaction model including current state publication, desired state acquisition, +vehicle-side reconciliation, and convergence monitoring. It further establishes constraints and guarantees such as +vehicle-side decision authority, deterministic enforcement paths, secure communication, and auditability. + +The interface is designed to be extensible and transport-agnostic, enabling integration with diverse deployment +environments while preserving existing in-vehicle architecture and autonomy. + +Motivation +========== + +As S-CORE adoption scales from individual vehicles to fleet-level deployments, a consistent mechanism for system updates +and configuration management across heterogeneous vehicle platforms becomes necessary. +Today, integration with external orchestration systems is often implementation-specific, +which leads to fragmented interfaces and difficult cross-vehicle operability. + +Cross-Vehicle Operability +------------------------- + +In current projects, externally managed vehicle functions are often exposed through custom APIs and integration adapters. +This creates incompatible state models and observability semantics across vehicle programs, even when platform capabilities are similar. + +A common vehicle-side interface is required to make external state orchestration portable across deployments and suppliers. + +Operational Observability at Scale +---------------------------------- + +Fleet operations require consistent insight into vehicle runtime state, feature activation status, and health signals. +Without a standardized reporting model, diagnostics and governance workflows become tightly coupled to implementation details. + +S-CORE already provides key observability building blocks through Lifecycle health supervision, +analysis-infra logging, and tracing capabilities. + +VECI does not introduce a separate observability stack. Instead, it standardizes how orchestrator-relevant state is exposed +and correlated with these existing platform signals, so external systems can reason about vehicle behavior in a comparable +and machine-processable way. + +Safe External Influence +----------------------- + +External systems often need to provide desired constraints, rollout directives, or policy updates. +Without a standardized safety and policy validation path, these interactions can bypass local assumptions and increase risk. + +VECI establishes controlled injection points and a strict vehicle-side validation pipeline so external influence remains bounded, +auditable, and aligned with local safety/security constraints. + +Without a standardized interface, systems cannot reliably: + +* expose orchestratable platform state in a common form, +* report runtime and health state in a consistent and machine-readable way, +* accept desired state and enforce convergence under local safety and security rules. + +VECI addresses this gap by defining a standardized, vehicle-side interaction contract that enables scalable observability, +control, and policy governance across heterogeneous fleets while preserving local authority. + + +Rationale +========= + +VECI is designed as a state-oriented semantic interface on top of existing S-CORE runtime capabilities. Traditional +integration approaches rely on proprietary adapters and ad-hoc APIs, which are difficult to scale and validate across +vendors and deployments. By introducing a common model for state, control, and policy exchange, VECI enables +interoperable external interaction without requiring fundamental changes to core modules. + +The vehicle remains the final authority for all externally requested actions. Inputs from external systems are validated +against local constraints, trust settings, and safety policies before being accepted or applied. + +This design was selected to keep core platform behavior deterministic while still enabling dynamic external coordination. +Rather than introducing a new orchestration runtime, VECI reuses existing lifecycle, communication, and policy mechanisms +through stable integration hooks. + + +Scope Overview +-------------- + +In scope: + +- Standardized vehicle-side desired state interface for selected capabilities +- Structured state publication for observability and fleet operations +- Policy and constraint injection with local validation and enforcement +- State convergence visibility (accepted, progressing, converged, rejected) +- Integration with existing S-CORE modules through additive interfaces + +Out of scope: + +- Definition or implementation of cloud-side orchestration systems +- OEM-specific decision-making strategies for optimization or planning +- Direct remote actuation paths that bypass vehicle-side policy checks +- Replacement of existing in-vehicle lifecycle, orchestration, or IPC mechanisms + + +Specification +============= + +VECI defines a standardized vehicle-side interaction model for external orchestrators based on state-seeking. +The interface is structured around desired state exchange and reconciliation safeguards. +A vehicle-side coordination component is responsible for mediating all external interactions. + +Interaction Model +_________________ + +VECI follows a state-oriented interaction pattern: + +1. The vehicle publishes selected current state and exposed state schema. +2. An external orchestrator provides desired target state and/or policy constraints. Desired state may be submitted directly or staged at an accessible location for vehicle retrieval. + The orchestrator may optionally send a notification that a new desired state version is available. +3. The vehicle retrieves the desired state at its own pace and applies freshness checks to prevent stale reconciliation. +4. The vehicle validates each desired state update against trust, schema, semantic, policy, and runtime gates. +5. Accepted desired state is reconciled via existing platform mechanisms and reported with structured convergence status and diagnostics. + Continuous reconciliation/monitoring is optional and can be enabled or disabled by vehicle-side configuration or policy. + +This flow ensures external intent can be expressed as target state while preserving vehicle-side authority over +admission, reconciliation strategy, and execution boundaries. + +State Exposure and Observability +________________________________ + +The vehicle publishes selected runtime state, configuration status, and health indicators in a structured model. +State publication supports both pull and event-driven update patterns. +Only explicitly exposed signals and metadata are made available to external systems. + +State data is versioned and timestamped to support consistency checks, traceability, and replay-safe processing. + +Desired State Interface +_______________________ + +VECI provides standardized desired state endpoints for platform components and applications. +Desired state updates represent target conditions instead of direct low-level actuation commands. +All desired state updates are versioned, typed, and associated with explicit preconditions. + +Each state domain defines: + +- expected desired/current state schema and semantic constraints, +- admission preconditions and safety gates, +- convergence acknowledgement and completion semantics. + +Policy and Constraint Injection +_______________________________ + +External systems may submit desired constraints or policy inputs, such as execution limits, feature activation constraints, +or operating envelopes. +Injected policies are treated as proposals and must pass local policy checks before activation. +Policy priority and conflict resolution rules are defined by the vehicle-side runtime. + +Policy activation supports explicit validity windows and scoped applicability to avoid unintended global side effects. + +Validation and Enforcement Pipeline +___________________________________ + +Every desired state update passes through authentication, authorization, schema validation, semantic validation, +and policy compliance checks before reconciliation. +Reconciliation is admitted only if local rules, safety constraints, and current system state permit it. +Rejected updates produce explicit status codes and diagnostic context. + +Validation outcomes are recorded to support post-event analysis and compliance evidence. + +Execution and Monitoring +________________________ + +Accepted desired state updates are realized through existing lifecycle and orchestration mechanisms. +VECI provides reconciliation status, progress, and converged/failed outcomes for observability. +Timeout handling and rollback or fallback behavior are supported for bounded fault handling. + +The vehicle runtime may operate in either mode: + +- on-demand reconciliation per desired state version (vehicle-initiated), or +- continuous reconciliation/monitoring until convergence criteria are met. + +Continuous reconciliation is optional and can be switched on or off by vehicle-side configuration or policy. + +Execution must remain deterministic for predefined operating scenarios and degrade gracefully in error conditions. + +Security and Trust +__________________ + +All interactions must be authenticated and integrity-protected. +Trust relationships with external systems are managed through verifiable identities and revocable credentials. +The interface supports runtime revocation and trust re-establishment without requiring platform restart. + +Security-relevant actions must be auditable end-to-end, including requester identity, policy context, and decision outcome. + +State Reconciliation Semantics +______________________________ + +VECI defines explicit semantics for state reconciliation: + +- desired state versioning and monotonic update handling, +- conflict handling between concurrent desired state updates, +- configurable reconciliation mode (one-shot or continuous), +- partial convergence reporting when some state domains cannot be fulfilled, +- stable final states for accepted or rejected reconciliation attempts. + +The reconciliation strategy is local to the vehicle runtime and is not controlled by the external orchestrator. + +Reconciliation Paradigms and Application Scenarios +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +VECI supports the following reconciliation paradigms. The selected paradigm can be configured per vehicle, +per state domain, or per deployment profile. + +1. Continuous reconciliation + +The vehicle continuously evaluates current state against desired state and keeps driving convergence while conditions change. + +Typical scenarios: + +- safety- or availability-relevant states that must stay within a target envelope, +- long-running state goals that can drift due to environment or resource contention, +- closed-loop fleet operations requiring near-real-time convergence supervision. + +2. On-demand reconciliation (vehicle-initiated) + +The vehicle decides when to fetch/evaluate desired state and performs reconciliation in discrete cycles. + +Typical scenarios: + +- bandwidth-constrained or intermittently connected environments, +- energy-sensitive platforms where periodic reconciliation is preferred over continuous processing, +- maintenance windows or scheduled update campaigns. + +3. Push-triggered reconciliation (orchestrator-initiated, vehicle subscribes) + +The orchestrator emits a new desired-state notification; subscribed vehicles treat this as a trigger to retrieve and +reconcile the referenced desired state version. + +Typical scenarios: + +- event-driven fleet rollouts requiring faster reaction than periodic pull, +- coordinated policy changes across many vehicles, +- staged desired-state publication where notification and payload distribution are decoupled. + +In all paradigms, final admission and execution remain vehicle-side decisions subject to local trust, safety, +and policy checks. + +Integration Boundaries +______________________ + +VECI augments existing S-CORE modules through well-defined integration points, including lifecycle management, +communication/IPC abstractions, and platform security services. +The interface does not define any external orchestration backend and does not mandate cloud architecture choices. + + +Deployment Profiles +___________________ + +The VECI model supports multiple deployment profiles: + +- vehicle-to-cloud fleet management, +- vehicle-to-edge control within local infrastructure, +- hybrid deployments combining cloud governance with edge-local execution. + +The protocol-level behavior remains consistent across profiles; only transport and deployment topology vary. + + +Versioning and Compatibility +____________________________ + +Interface contracts and data models are versioned to support incremental evolution. +Backward-compatible extensions are preferred; breaking changes require explicit version transitions. + + +Requirements +____________ + +.. note:: + + Requirements for this feature are under development. + + +Open Topics +=========== + +The following topics are expected to be refined in subsequent requirements and architecture work: + +- canonical state taxonomy and data model definitions, +- desired state conflict resolution strategy across concurrent external authorities, +- audit log retention and evidence requirements for regulated deployments, +- conformance profiles for different connectivity and security environments. + + +Backwards Compatibility +======================= + +VECI is an incremental extension and does not replace existing in-vehicle lifecycle or communication mechanisms. +Integration is achieved through additive interfaces and hooks, preserving established module responsibilities and +runtime behavior. + + +Security Impact +=============== + +VECI introduces security-sensitive interaction paths between external systems and in-vehicle runtime functions. +The following non-complete list highlights key security considerations: + +- Endpoint Authentication + - All external endpoints must be strongly authenticated before interaction + - Credentials must be revocable and bound to scoped permissions +- Authorization and Least Privilege + - External desired state updates must be authorized per capability, context, and policy + - Access must be minimized to explicitly exposed state and policy surfaces +- Message Integrity and Replay Protection + - All interface messages must be integrity-protected and freshness-validated +- Policy Integrity + - Injected constraints must be validated, versioned, and auditable + - Unauthorized or conflicting policy changes must be rejected + + +Safety Impact +============= + +VECI can influence execution behavior through externally provided inputs and therefore requires strict vehicle-side safety guardrails. +The following list gives an idea of safety considerations and is not complete. An in-depth safety analysis must be conducted in the future. + +- Vehicle-side Authority + - Final decision authority for any desired state update remains on the vehicle +- Safe State Protection + - Desired state reconciliation must not bypass local safety constraints or lifecycle guards +- Bounded Failure Handling + - Communication loss, invalid policies, and reconciliation failures must degrade gracefully + + +License Impact +============== + +VECI is expected to be implemented primarily using Free and Open Source Software (FOSS), in alignment with the Eclipse Foundation's licensing principles. + +- All new components developed under this feature shall be licensed under the Apache 2.0 License +- No additional licensing constraints are introduced by this feature request beyond those already adopted in S-CORE + + +How to Teach This +================= + +The following sources are recommended for onboarding: + +- This feature request document and its linked requirements +- The S-CORE platform documentation for related features such as AI Platform, Communication, Lifecycle, and Security/Crypto +- Feature Request issue discussion for VECI (#2751) and related VACP context (#2752) + + +References +========== + +- VECI Feature Request issue: https://github.com/eclipse-score/score/issues/2751 +- VACP Feature Request issue (related context): https://github.com/eclipse-score/score/issues/2752 +- AI Platform Feature Request PR (format and process reference): https://github.com/eclipse-score/score/pull/1258