AkiraOS API Stability Policy
Every public header in AkiraOS carries two Doxygen tags that declare its contractual stability:
/**
* @stability stable // or: experimental | deprecated
* @since 1.3 // version in which this API first appeared
*/
Stability Levels
stable
The API is production-ready and covered by a two-release deprecation notice before any breaking change or removal.
Rules:
- Signatures, struct layouts, and error codes will not change without
first issuing a
deprecatednotice in the immediately preceding release. - A deprecated API must remain available and functional for at least two minor releases after the deprecation notice.
- Breaking changes in a stable API require a major version bump.
- Renaming a stable symbol requires a compatibility alias for two releases.
experimental
The API exists and is usable, but no compatibility guarantee is made.
Rules:
- May change signature, semantics, or be removed in any release without prior notice.
- Will not be documented in the main Getting Started guide until promoted.
- Callers must opt in by defining
AKIRA_ACCEPT_EXPERIMENTALor by including the header explicitly.
(Feature flag enforcement will land in v1.6.) - Promotion to
stablerequires: two releases without API change, full test coverage, and a public RFC issue.
deprecated
The API is scheduled for removal and must not be used in new code.
Rules:
- A
deprecatedheader or function emits a compile-time warning via__attribute__((deprecated("use X instead"))). - Will be removed no sooner than two minor releases after the deprecation tag appears.
- The deprecation notice states the replacement symbol.
-
Example annotation:
/** * @deprecated Since 1.5 — use akira_storage_open() instead. */ __attribute__((deprecated("use akira_storage_open()"))) int legacy_fs_open(const char *path, int flags);
Versioning Alignment
AkiraOS uses Semantic Versioning (MAJOR.MINOR.PATCH):
| Bump | Meaning |
|---|---|
| PATCH | Bug fixes; no API changes. |
| MINOR | New stable APIs added; backward-compatible. Deprecated APIs may be introduced. |
| MAJOR | Breaking changes to stable APIs; deprecated APIs removed. |
The @since X.Y tag records the minor version in which the API first
became available (patch is omitted because patch releases never add APIs).
Process: Promoting experimental → stable
- Open a GitHub issue titled
[RFC] Promote <header> to stable. - API must have been unchanged for two consecutive minor releases.
- Requires ≥ 90% line coverage in the test suite.
- At least one board other than native_sim must pass CI with the new stable designation.
- PR adds
@stability stableand updates this document’s table below.
Current API Surface (v1.6.5)
| Header | Stability | Since |
|---|---|---|
include/akira_native_api.h |
stable | 1.4 |
include/lib/akira_time.h |
stable | 1.3 |
include/modules/akira_log_module.h |
stable | 1.4 |
include/modules/akira_time_module.h |
stable | 1.4 |
include/connectivity/radio_interface.h |
experimental | 1.5 |
include/connectivity/akira_mesh.h |
experimental | 1.5 |
include/connectivity/matter_manager.h |
experimental | 1.5 |
include/connectivity/thread_manager.h |
experimental | 1.5 |
src/akira.h |
stable | 1.0 |
src/api/akira_api.h |
stable | 1.0 |
src/api/akira_common_api.h |
stable | 1.0 |
src/api/akira_display_api.h |
stable | 1.2 |
src/api/akira_memory_api.h |
stable | 1.2 |
src/api/akira_gpio_api.h |
stable | 1.3 |
src/api/akira_storage_api.h |
stable | 1.3 |
src/api/akira_timer_api.h |
stable | 1.3 |
src/api/akira_adc_api.h |
stable | 1.4 |
src/api/akira_ble_api.h |
stable | 1.4 |
src/api/akira_i2c_api.h |
stable | 1.4 |
src/api/akira_lifecycle_api.h |
stable | 1.4 |
src/api/akira_net_api.h |
stable | 1.4 |
src/api/akira_power_api.h |
stable | 1.4 |
src/api/akira_pwm_api.h |
stable | 1.4 |
src/api/akira_sensor_api.h |
stable | 1.4 |
src/api/akira_settings_api.h |
stable | 1.4 |
src/api/akira_system_api.h |
stable | 1.4 |
src/api/akira_uart_api.h |
stable | 1.4 |
src/api/akira_wdt_api.h |
stable | 1.4 |
src/api/akira_hid_api.h |
experimental | 1.4 |
src/api/akira_ipc_api.h |
experimental | 1.4 |
src/api/akira_rf_api.h |
experimental | 1.4 |
src/runtime/security.h |
stable | 1.3 |
src/runtime/security/app_signing.h |
stable | 1.3 |
src/runtime/security/sandbox.h |
stable | 1.3 |
src/runtime/security/trust_levels.h |
stable | 1.3 |
src/runtime/app_manager/app_manager.h |
stable | 1.4 |
src/runtime/manifest_parser.h |
stable | 1.4 |
src/runtime/akira_runtime.h |
stable | 1.3 |
src/connectivity/ota/ota_manager.h |
stable | 1.4 |
src/lib/error_codes.h |
stable | 1.0 |
src/lib/mem_helper.h |
stable | 1.2 |
src/lib/path_utils.h |
stable | 1.3 |
src/lib/simple_json.h |
stable | 1.4 |
src/shell/akira_shell.h |
stable | 1.3 |
src/storage/fs_manager.h |
stable | 1.3 |
src/drivers/platform_hal.h |
stable | 1.2 |
src/drivers/driver_registry.h |
stable | 1.3 |
src/drivers/wdt/akira_wdt.h |
stable | 1.4 |
src/drivers/power/power_manager.h |
stable | 1.4 |
src/drivers/sensors/button.h |
stable | 1.3 |
| All connectivity/cloud/* headers | experimental | 1.5 |
| All connectivity/hid/* headers | experimental | 1.4 |
| All connectivity/bluetooth/* headers | experimental | 1.4 |
| All drivers/rf/* headers | experimental | 1.4 |
| All drivers/display/* headers | experimental | 1.4 |
| All drivers/sensors/* (except button) | experimental | 1.4 |
WASM import ABI
The functions and signatures a WASM app imports from AkiraOS (the “env” module
and akira_log / akira_time, declared in AkiraSDK/include/akira_api.h) are a
versioned interface, separate from the firmware version because the SDK ships
separately (include/akira_abi.h):
- MAJOR increments when an import is removed, renamed, or its signature changes. Apps built for an older major are refused at load.
- MINOR increments when an import is added. Older apps keep working; a newer app’s calls to functions this firmware lacks trap at call time.
Apps declare the ABI they target with the manifest abi key. CI
(scripts/check_wasm_abi.py) fails when the firmware’s exported natives and the
SDK header drift apart outside the recorded allowlist.
Frozen capability bit numbers
Core capability bit numbers (AKIRA_CAP_*, bits 0–47 in runtime/security.h)
are frozen: they appear in raw form in configuration
(CONFIG_AKIRA_UNSIGNED_APP_CAP_MASK), audit logs and the cloud protocol. A new
core capability takes the next free bit and is never renumbered. Product
capabilities use bits 48–63 (AKIRA_CAPABILITY_DEFINE).
Module extension APIs
include/akira_capability.h, include/akira_native_registry.h,
include/akira_hooks.h and include/akira_abi.h are the interfaces product
firmware builds against. They are experimental in 1.6: they may change in a
minor release while the maker workflow settles, then move to stable.
Deprecation Example Workflow
Release 1.5.x: Introduce replacement, mark old API:
/** @deprecated Since 1.5 — use akira_power_get_level() instead. */
__attribute__((deprecated("use akira_power_get_level()")))
int legacy_battery_read(void);
Release 1.6.0: Warning still emitted; migration guide published.
Release 1.7.0: API removed; CHANGELOG entry under ### Removed.
Last updated: 2026-09-14 (AkiraOS v1.6.5)