Refactor app loading and window management (#609)

Modules/app-module/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.20)
+
+include("${CMAKE_CURRENT_LIST_DIR}/../../Buildscripts/module.cmake")
+
+file(GLOB_RECURSE SOURCE_FILES "source/*.c*")
+
+tactility_add_module(app-module
+    SRCS ${SOURCE_FILES}
+    PRIV_INCLUDE_DIRS private/
+    INCLUDE_DIRS include/
+    REQUIRES TactilityKernel service-module minitar
+)

Modules/app-module/LICENSE-Apache-2.0.md

@@ -0,0 +1,195 @@
+Apache License
+==============
+
+_Version 2.0, January 2004_  
+_&lt;<http://www.apache.org/licenses/>&gt;_
+
+### Terms and Conditions for use, reproduction, and distribution
+
+#### 1. Definitions
+
+“License” shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+“Licensor” shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+“Legal Entity” shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, “control” means **(i)** the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
+outstanding shares, or **(iii)** beneficial ownership of such entity.
+
+“You” (or “Your”) shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+“Source” form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+“Object” form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+“Work” shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+“Derivative Works” shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+“Contribution” shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+“submitted” means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as “Not a Contribution.”
+
+“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+#### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+#### 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+#### 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+* **(b)** You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+* **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+#### 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+#### 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+#### 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+#### 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+#### 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+_END OF TERMS AND CONDITIONS_
+
+### APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets `[]` replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same “printed page” as the copyright notice for easier identification within
+third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+      http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+

Modules/app-module/devicetree.yaml

@@ -0,0 +1,3 @@
+dependencies:
+  - TactilityKernel
+  - Modules/service-module

Modules/app-module/include/app/event.h

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <tactility/error.h>
+#include <tactility/freertos/freertos.h>
+#include <tactility/freertos/task.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Identifies the kind of app-lifecycle event delivered through app_event_await(). */
+enum AppEventType {
+    APP_EVENT_RESULT, // struct AppResultEventData
+    APP_EVENT_CLOSE,  // no data - terminate now, permanently
+};
+
+/** Data for APP_EVENT_RESULT. */
+struct AppResultEventData {
+    uint32_t launch_id;
+    /** The child app instance's own AppMainFn/AppLoaderApi::run() return value. By convention:
+     * 0 = Ok, 1 = Cancelled, 2 = Error. Apps that need to hand back more than this (e.g. picked
+     * text, a path) expose their own "get last result" getter instead - see e.g.
+     * tt::app::inputdialog::getLastText(). */
+    int32_t result;
+};
+
+struct AppEvent {
+    enum AppEventType type;
+    /** Stamped by app_event_emit(); any value passed in by the caller is ignored. */
+    uint64_t timestamp;
+    /** Valid only when type == APP_EVENT_RESULT. */
+    struct AppResultEventData result;
+};
+
+/**
+ * Number of events that can be queued per subscription before app_event_emit() starts
+ * returning ERROR_RESOURCE (dropping the newest event, preserving FIFO order of what's
+ * already queued). Deliberately generous: app-module's scheduler is the only emitter and it
+ * serializes app-lifecycle transitions, so a given app can't realistically receive events
+ * faster than the scheduler produces them one at a time.
+ */
+#define APP_EVENT_QUEUE_CAPACITY 4
+
+/**
+ * Caller-owned subscription node. Unlike TactilityKernel's system_event poll subscription
+ * (which coalesces to the latest value), this queues events by value (FIFO) since dropping an
+ * APP_EVENT_RESULT would be unacceptable.
+ * @warning Fields other than `app_instance_id` are for internal use only; do not read or write
+ * them directly.
+ */
+struct AppEventSubscription {
+    /** The app instance this subscription receives events for; set by the caller before app_event_subscribe(). */
+    uint32_t app_instance_id;
+
+    TaskHandle_t task;
+
+    struct AppEvent queue[APP_EVENT_QUEUE_CAPACITY];
+    uint8_t head;
+    uint8_t count;
+
+    struct AppEventSubscription* next;
+};
+
+/**
+ * Register a subscription for events addressed to @a sub->app_instance_id.
+ * @warning Does not work in ISR context.
+ * @param[in,out] sub subscription to register; caller sets @a sub->app_instance_id beforehand,
+ * owns the storage, and must keep it alive (and stationary) until unsubscribed
+ * @return ERROR_NONE on success
+ */
+error_t app_event_subscribe(struct AppEventSubscription* sub);
+
+/**
+ * Remove a previously registered subscription.
+ * @warning Does not work in ISR context.
+ * @return ERROR_NONE on success, ERROR_NOT_FOUND if no matching subscription exists
+ */
+error_t app_event_unsubscribe(struct AppEventSubscription* sub);
+
+/**
+ * Deliver @a event to every subscription registered for @a app_instance_id (normally exactly one).
+ * @warning Does not work in ISR context.
+ * @retval ERROR_NONE delivered to at least one subscription
+ * @retval ERROR_NOT_FOUND no subscription is registered for @a app_instance_id
+ * @retval ERROR_RESOURCE at least one matching subscription's queue was full; the event was
+ * dropped for that subscription (still delivered to any other matching subscription)
+ */
+error_t app_event_emit(uint32_t app_instance_id, const struct AppEvent* event);
+
+/**
+ * Pop the next event for @a sub, blocking up to @a timeout if the queue is currently empty.
+ * @retval ERROR_NONE @a out_event was filled
+ * @retval ERROR_TIMEOUT no event arrived before the timeout elapsed
+ */
+error_t app_event_await(struct AppEventSubscription* sub, struct AppEvent* out_event, TickType_t timeout);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/install.h

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/error.h>
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Computes the install directory for @a app_id (does not check whether anything is actually
+ * installed there).
+ * @param[out] path always NULL-terminated on return, even on failure (empty string if
+ * @a path_size == 0 - nothing is written in that case; otherwise at least "" is written)
+ * @retval ERROR_NONE on success
+ * @retval ERROR_BUFFER_OVERFLOW @a path_size is too small to hold the path (including the
+ * NULL terminator)
+ * @retval ERROR_NOT_FOUND the app install location isn't available (e.g. no SD card)
+ */
+error_t app_get_install_path(const char* app_id, char* path, size_t path_size);
+
+/**
+ * Installs an app from a tarball at @a source_path: extracts it into the app install directory,
+ * parses the extracted manifest.properties (see app/metadata.h) to determine its id, then
+ * registers it with app_manager_add() as an AppLocation{APP_LOCATION_PATH, <install dir>} app.
+ * If an app with the same id is already installed (via a previous app_install() call), it is
+ * uninstalled first - stopped if running, its old install directory removed - before the new
+ * one takes its place.
+ * @param[in] source_path path to a tar file containing the app (must have manifest.properties
+ * at its root)
+ * @retval ERROR_NONE on success
+ * @retval ERROR_NOT_FOUND @a source_path doesn't exist / can't be read
+ * @retval ERROR_INVALID_ARGUMENT the tarball has no valid manifest.properties at its root
+ */
+error_t app_install(const char* source_path);
+
+/**
+ * Uninstalls a previously app_install()-ed app: stops it if currently running, deletes its
+ * install directory, and unregisters it (app_manager_remove()).
+ * @param[in] app_id the id the app was installed under (AppMetadata::app_id)
+ * @retval ERROR_NONE on success
+ * @retval ERROR_NOT_FOUND no such app was installed via app_install()
+ */
+error_t app_uninstall(const char* app_id);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/instance.h

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Identifies a running (or previously running) app instance. 0 is never a valid instance id. */
+typedef uint32_t AppInstanceId;
+
+/** Lifecycle state of a running (or previously running) app instance. Every app instance owns
+ * its own task for its entire lifetime - there is no "saved, task given up" state. */
+typedef enum {
+    APP_INSTANCE_STATE_STARTING,
+    APP_INSTANCE_STATE_ACTIVE,
+    APP_INSTANCE_STATE_STOPPING,
+    APP_INSTANCE_STATE_STOPPED,
+} AppInstanceState;
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/loader.h

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/manifest.h>
+#include <tactility/error.h>
+#include <stdint.h>
+#include "location.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** service-module id the AppLoaderApi implementation for AppManifest::location.type ==
+ * APP_LOCATION_MEMORY must register under. Implemented by app-module itself (source/app_internal_loader.cpp). */
+#define APP_LOADER_MEMORY_SERVICE_ID "app-loader-memory"
+
+/** service-module id the AppLoaderApi implementation for AppManifest::location.type ==
+ * APP_LOCATION_PATH must register under. Implemented by a platform module (e.g. app-esp32-module). */
+#define APP_LOADER_PATH_SERVICE_ID "app-loader-path"
+
+/**
+ * Entry point signature for an APP_LOCATION_MEMORY app: a function linked directly into this
+ * firmware binary. Called on the dedicated task app-module's scheduler spawns for this instance,
+ * blocking for the app's whole lifetime - same contract as an external app's main(), plus
+ * @a app_instance_id identifying this running instance (use it with
+ * app_event_subscribe()/window_manager_create()/app_manager_finish()/etc.).
+ * AppManifest::location.location holds this cast to void*.
+ */
+typedef int32_t (*AppMainFn)(uint32_t app_instance_id, int argc, char* argv[]);
+
+typedef void* AppRuntime;
+
+/**
+ * Pluggable mechanism for loading and executing an app.
+ */
+struct AppLoaderApi {
+    /**
+     * Prepares an app instance for execution (e.g. read + relocate its binary).
+     * @param[in] location the location to load the elf from
+     * @param[out] out_runtime opaque handle to whatever load() allocated; passed back to run()/unload()
+     */
+    error_t (*load)(struct AppLocation location, AppRuntime* out_runtime);
+
+    /**
+     * Blocking: runs the app to completion.
+     * @param[in] runtime handle produced by load()
+     * @param[in] app_instance_id the running instance's id
+     * @param[in] argc the amount of arguments in @a argv
+     * @param[in] argv the array of string pointers (can be NULL)
+     */
+    int32_t (*run)(AppRuntime runtime, uint32_t app_instance_id, int argc, char* argv[]);
+
+    /** Releases whatever load() allocated. Called after run() returns. */
+    void (*unload)(AppRuntime runtime);
+};
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/location.h

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+enum AppLocationType {
+    APP_LOCATION_MEMORY,
+    APP_LOCATION_PATH,
+};
+
+struct AppLocation {
+    enum AppLocationType type;
+    /** Meaning depends on `type`; see AppLocationType. */
+    void* location;
+};
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/manager.h

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/instance.h>
+#include <app/manifest.h>
+
+#include <tactility/error.h>
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Register an app manifest.
+ * @retval ERROR_INVALID_ARGUMENT a manifest with the same id is already registered
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_add(const struct AppManifest* manifest);
+
+/**
+ * Unregister a previously-added manifest.
+ * @retval ERROR_NOT_FOUND no manifest with this id is registered
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_remove(const char* id);
+
+/** @return the manifest, or NULL if not found. */
+const struct AppManifest* app_manager_find_manifest(const char* id);
+
+/**
+ * Calls `@a` visitor once for every registered manifest. Iteration order is unspecified.
+ * `@warning` `@a` visitor runs with app-module's internal registry lock held. Do not call any
+ * app_manager_*() function from inside `@a` visitor - copy out what you need and act on it after
+ * this call returns.
+ */
+typedef void (*AppManifestVisitorFn)(const struct AppManifest* manifest, void* context);
+void app_manager_for_each_manifest(AppManifestVisitorFn visitor, void* context);
+
+/**
+ * Starts a new instance of the app registered under @a id. Every app instance gets its own
+ * dedicated task for its entire lifetime - starting an app never asks any other app to give up
+ * its task, and multiple instances (of the same or different apps) can be Active at once.
+ * @param[in] id the manifest id to start
+ * @param[out] out_app_instance_id the id of the new app instance
+ * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_start(const char* id, AppInstanceId* out_app_instance_id);
+
+/**
+ * Same as app_manager_start(), but also passes @a argc/@a argv to the new instance's own main
+ * function (see app/loader.h's AppMainFn) - modelled on a C program's main(argc, argv). For
+ * regular (non-modal) navigations that need to pass data to the target app (e.g. "show details
+ * for this app id") without expecting a result back.
+ * @param[in] argv @a argc strings; app-module makes its own deep copy before returning, so
+ * @a argv and the strings it points to may be freed/go out of scope immediately after this call
+ * returns (e.g. safe to pass a stack-local array of a caller's own std::string::c_str()s).
+ */
+error_t app_manager_start_with_parameters(const char* id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id);
+
+/**
+ * Starts @a id as a modal child of @a parent_instance_id, for the purpose of receiving a
+ * result. The parent keeps running (window_manager's own multi-window stack handles burying its
+ * window while the child is shown).
+ *
+ * When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id -
+ * result is whatever the child's AppMainFn/AppLoaderApi::run() returned - unless
+ * @a parent_instance_id is 0, in which case no result is delivered (fire-and-forget, for
+ * callers with no app_instance_id of their own). The parent is then responsible for calling
+ * app_manager_stop() on the child's instance id to fully reap it. Children that need to hand
+ * back more than an int32_t (e.g. picked text, a path) expose their own "get last result"
+ * getter for the parent to call after receiving the event - see e.g.
+ * tt::app::inputdialog::getLastText().
+ * @param[in] argv @a argc strings; app-module makes its own deep copy before returning (same as
+ * app_manager_start_with_parameters()), so @a argv and the strings it points to may be
+ * freed/go out of scope immediately after this call returns.
+ * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_start_for_result(const char* id, AppInstanceId parent_instance_id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id);
+
+/**
+ * Stop an app instance permanently. Emits APP_EVENT_CLOSE and bound-waits for its task to exit
+ * if it was running.
+ * @warning Must not be called from the instance's own task (it bound-waits via thread_join(),
+ * which asserts against joining yourself) - an app closing itself must call app_manager_finish()
+ * instead, right before returning from its own AppMainFn/AppLoaderApi::run().
+ */
+error_t app_manager_stop(AppInstanceId app_instance_id);
+
+/**
+ * Called by an app instance, from its own task, right before it returns in response to
+ * APP_EVENT_CLOSE - whether that close was self-initiated (e.g. its own back button) or came
+ * from someone else. Marks this instance Stopped immediately (rather than waiting for its task
+ * to actually exit) so app_manager_get_state()/app_manager_get_topmost_instance_id() reflect the
+ * closure as soon as the app has decided to close, not just once its task has fully unwound.
+ * @warning Does not join or free this instance's own task/ledger entry (can't - this runs on
+ * that very task); those are cleaned up on a later app_manager_stop() call, same as any
+ * self-terminating instance.
+ */
+error_t app_manager_finish(AppInstanceId app_instance_id);
+
+/** @return the instance's current state, or APP_INSTANCE_STATE_STOPPED if the id is unknown. */
+AppInstanceState app_manager_get_state(AppInstanceId app_instance_id);
+
+/**
+ * @param[out] out_app_instance_id set to the instance id of the topmost currently-Active app -
+ * the most recently started of whichever instances are Active (a modal child launched via
+ * app_manager_start_for_result() stays Active alongside its parent while shown, so this
+ * correctly picks the child, not the parent, while a dialog is up).
+ * @retval ERROR_NOT_FOUND no app is Active
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_get_topmost_instance_id(AppInstanceId* out_app_instance_id);
+
+/**
+ * Same as app_manager_get_topmost_instance_id(), but resolves straight to the topmost app's
+ * manifest id string.
+ * @param[out] buffer always NULL-terminated on return, even on failure (empty string if
+ * @a buffer_size == 0 - nothing is written in that case; otherwise at least "" is written)
+ * @retval ERROR_NOT_FOUND no app is Active
+ * @retval ERROR_BUFFER_OVERFLOW @a buffer_size is too small to hold the id (including the NULL
+ * terminator)
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_get_topmost_app_id(char* buffer, size_t buffer_size);
+
+/**
+ * Registers @a path as a directory to scan for app manifests - each direct subdirectory of
+ * @a path is expected to hold a manifest.properties (see app/metadata.h), matching the layout
+ * app_install() creates ({install dir}/{app_id}/manifest.properties), though this is not
+ * install/uninstall - it only ever adds/removes manifest registrations, never touches files on
+ * disk or running instances. No-op if @a path is already registered. Does not scan immediately -
+ * call app_manager_install_path_scan() to do that.
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_install_path_add(const char* path);
+
+/**
+ * Scans every path registered via app_manager_install_path_add(): registers
+ * (app_manager_add()) any direct subdirectory with a valid manifest.properties that isn't
+ * already registered, and unregisters (app_manager_remove() only - does not stop it if running,
+ * does not delete anything) any manifest a previous scan registered whose directory has since
+ * disappeared. Safe to call repeatedly (e.g. after an SD card is mounted/unmounted).
+ */
+void app_manager_install_path_scan(void);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/manifest.h

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "location.h"
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Broad classification of an app, used for grouping/launcher presentation. */
+enum AppCategory {
+    APP_CATEGORY_SYSTEM,
+    APP_CATEGORY_SETTINGS,
+    APP_CATEGORY_USER,
+};
+
+/** Bit flags for AppManifest::flags. */
+enum AppManifestFlags {
+    /** Excluded from generic app-browsing UIs (AppList, Settings) - for apps only ever reached
+     * by direct navigation (modal dialogs, detail views that require parameters, wizard/
+     * bootstrap steps). */
+    APP_MANIFEST_FLAG_HIDDEN = 0b00000001,
+};
+
+/** Describes a registrable app. One manifest exists per app id. */
+struct AppManifest {
+    /** Unique app identifier. Should never be NULL. */
+    const char* id;
+    /** Human-readable name. Should never be NULL. */
+    const char* name;
+    enum AppCategory category;
+    struct AppLocation location;
+    /** Bitmask of AppManifestFlags. Most apps should leave this 0. */
+    uint8_t flags;
+};
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/metadata.h

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/error.h>
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define APP_METADATA_TARGET_SDK_LENGTH 16
+#define APP_METADATA_APP_ID_LENGTH 32
+#define APP_METADATA_APP_NAME_LENGTH 32
+#define APP_METADATA_APP_VERSION_NAME_LENGTH 16
+
+struct AppMetadata {
+
+    /**
+     * The SDK version that was used to compile this app. (e.g. "0.6.0")
+     * Must be NULL-terminated.
+     */
+    char target_sdk[APP_METADATA_TARGET_SDK_LENGTH + 1];
+
+    /**
+     * The identifier by which the app is launched by the system and other apps.
+     * Must be NULL-terminated.
+     */
+    char app_id[APP_METADATA_APP_ID_LENGTH + 1];
+
+    /**
+     * The user-readable name of the app. Used in UI.
+     * Must be NULL-terminated.
+     */
+    char app_name[APP_METADATA_APP_NAME_LENGTH + 1];
+
+    /**
+     * The version as it is displayed to the user (e.g. "1.2.0")
+     * Must be NULL-terminated.
+     */
+    char app_version_name[APP_METADATA_APP_VERSION_NAME_LENGTH + 1];
+
+    /** The technical version (must be incremented with new releases of the app) */
+    uint64_t app_version_code;
+};
+
+/**
+ * Parses a manifest.properties file at @a path into @a out_metadata, auto-detecting the V1
+ * (sectioned, e.g. "[app]id=...") or V2 (flat dot-notation, e.g. "app.id=...") format from its
+ * first line.
+ * @retval ERROR_NONE on success
+ * @retval ERROR_NOT_FOUND the file doesn't exist / couldn't be opened
+ * @retval ERROR_INVALID_ARGUMENT the file isn't a valid manifest, or a field's value doesn't fit
+ * @a out_metadata's fixed-size buffers
+ */
+error_t app_metadata_parse(const char* path, struct AppMetadata* out_metadata);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/module.h

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/module.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern struct Module app_module;
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/paths.h

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <stddef.h>
+#include <tactility/error.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Get the user data directory for an app. Survives OS upgrades. No trailing "/".
+ * @param[in] app_id non-null app id
+ * @param[out] out_path buffer to store the path
+ * @param[in] out_path_size size of the output buffer
+ * @retval ERROR_BUFFER_OVERFLOW if out_path_size is too small
+ * @retval ERROR_NONE on success
+ */
+error_t app_paths_get_user_data_directory(const char* app_id, char* out_path, size_t out_path_size);
+
+/**
+ * @brief Get a path within the user data directory for an app.
+ * @param[in] app_id non-null app id
+ * @param[in] child_path path without a "/" prefix
+ * @param[out] out_path buffer to store the path
+ * @param[in] out_path_size size of the output buffer
+ * @retval ERROR_BUFFER_OVERFLOW if out_path_size is too small
+ * @retval ERROR_NONE on success
+ */
+error_t app_paths_get_user_data_path(const char* app_id, const char* child_path, char* out_path, size_t out_path_size);
+
+/**
+ * @brief Get the assets directory for an app. Do not store configuration data here. No trailing "/".
+ * @param[in] app_id non-null app id
+ * @param[out] out_path buffer to store the path
+ * @param[in] out_path_size size of the output buffer
+ * @retval ERROR_BUFFER_OVERFLOW if out_path_size is too small
+ * @retval ERROR_NONE on success
+ */
+error_t app_paths_get_assets_directory(const char* app_id, char* out_path, size_t out_path_size);
+
+/**
+ * @brief Get a path within the assets directory for an app.
+ * @param[in] app_id non-null app id
+ * @param[in] child_path path without a "/" prefix
+ * @param[out] out_path buffer to store the path
+ * @param[in] out_path_size size of the output buffer
+ * @retval ERROR_BUFFER_OVERFLOW if out_path_size is too small
+ * @retval ERROR_NONE on success
+ */
+error_t app_paths_get_assets_path(const char* app_id, const char* child_path, char* out_path, size_t out_path_size);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/scheduler.h

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/instance.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @return the app_instance_id of whichever app instance's task is calling this (every app
+ * instance's task stashes it in its own thread-local storage when it starts), or 0 if called
+ * from a task that isn't a running app instance. An app's own main() typically calls this once,
+ * near the top, to learn its own instance id - see e.g. app_event_subscribe()/
+ * window_manager_create(), both of which need it.
+ */
+AppInstanceId app_scheduler_current_app_id(void);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/private/app/private/app_fs.h

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+// Minimal filesystem helpers shared by app-module internals that need to look at on-disk app
+// directories (app_install.cpp, manager.cpp's install-path scan) - app-module may not depend
+// upward on Tactility::file, so this is a small local re-implementation (see
+// app_metadata_parsing.cpp for the same constraint applied to properties-file loading).
+
+#include <tactility/filesystem/file_mutex.h>
+
+#include <cstring>
+#include <dirent.h>
+#include <string>
+#include <sys/stat.h>
+#include <vector>
+
+inline bool app_fs_is_directory(const std::string& path) {
+    struct stat result {};
+    FileMutex file_mutex;
+    file_mutex_get(&file_mutex, path.c_str());
+    file_mutex_lock(&file_mutex);
+    auto is_dir = stat(path.c_str(), &result) == 0 && S_ISDIR(result.st_mode);
+    file_mutex_unlock(&file_mutex);
+    return is_dir;
+}
+
+inline bool app_fs_is_file(const std::string& path) {
+    FileMutex file_mutex;
+    file_mutex_get(&file_mutex, path.c_str());
+    file_mutex_lock(&file_mutex);
+    struct stat result {};
+    auto retval = stat(path.c_str(), &result) == 0 && S_ISREG(result.st_mode);
+    file_mutex_unlock(&file_mutex);
+    return retval;
+}
+
+// Appends the full path of every direct subdirectory of @a path to @a out.
+// No-op (not an error) if @a path can't be opened.
+inline void app_fs_list_direct_subdirectories(const std::string& path, std::vector<std::string>& out) {
+    // Collect child names while the directory lock is held, then release it before classifying
+    // each one with app_fs_is_directory() - that function looks up and locks a FileMutex too,
+    // and file_mutex_get() resolves a child path to the same registered mutex as its parent
+    // mount. Calling it while still holding the directory's own lock would be a nested
+    // acquisition of that same (possibly non-recursive) mutex, and could self-deadlock.
+    std::vector<std::string> children;
+
+    FileMutex file_mutex;
+    file_mutex_get(&file_mutex, path.c_str());
+    file_mutex_lock(&file_mutex);
+    DIR* dir = opendir(path.c_str());
+    if (dir == nullptr) {
+        file_mutex_unlock(&file_mutex);
+        return;
+    }
+
+    struct dirent* entry;
+    while ((entry = readdir(dir)) != nullptr) {
+        if (std::strcmp(entry->d_name, ".") == 0 || std::strcmp(entry->d_name, "..") == 0) {
+            continue;
+        }
+        children.push_back(path + "/" + entry->d_name);
+    }
+
+    closedir(dir);
+    file_mutex_unlock(&file_mutex);
+
+    for (const auto& child_path : children) {
+        if (app_fs_is_directory(child_path)) {
+            out.push_back(child_path);
+        }
+    }
+}

Modules/app-module/private/app/private/app_ledger.h

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/instance.h>
+#include <app/manifest.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/freertos/freertos.h>
+#include <tactility/freertos/semphr.h>
+#include <tactility/freertos/task.h>
+
+#include <stdint.h>
+#include <string>
+#include <unordered_map>
+
+/**
+ * A dedicated completion signal(1) for one app instance's task, given as the
+ * literal last action app_task_main() takes before vTaskDelete().
+ * Heap-allocated with its own refcount (protected by app_ledger().mutex, not atomic)
+ * rather than owned by the ledger entry, since app_task_main() always erases that entry -
+ * and may run its exit path entirely - before app_scheduler_stop() ever looks for it:
+ * Whichever side(2) finishes with it last is the one that deletes `semaphore` and frees this struct.
+ *
+ * (1) Not the task's shared default FreeRTOS notification, which app_event.cpp's
+ * AppEventSubscription also uses - an unrelated event delivered to the same task could
+ * otherwise unblock a waiter early.
+ * (2) The exiting task, or a concurrent app_scheduler_stop() that found the entry in time and is waiting on `semaphore`
+ */
+struct AppCompletionSignal {
+    SemaphoreHandle_t semaphore;
+    /** Starts at 1, owned by app_task_main() until its own exit. app_scheduler_stop() takes an
+     * additional reference for as long as it's waiting on `semaphore`, if it finds the instance
+     * still running. Reaching 0 means deletion. */
+    int refcount = 1;
+};
+
+/** A registered/running app instance, as tracked internally by app-module. */
+struct AppInstanceRecord {
+    uint32_t id;
+    const AppManifest* manifest;
+    AppInstanceState state;
+    /** The FreeRTOS task currently executing AppLoaderApi::run() for this instance; NULL when not running. */
+    TaskHandle_t task;
+
+    /** 0 for a top-level launch (app_manager_start()). Non-zero for a modal child launched via
+     * app_manager_start_for_result() - the instance that receives this child's APP_EVENT_RESULT. */
+    uint32_t parent_id = 0;
+
+    /** This instance's completion signal - see AppCompletionSignal. Set once by
+     * app_scheduler_start(), never reassigned. */
+    AppCompletionSignal* completion = nullptr;
+};
+
+struct AppLedger {
+    std::unordered_map<std::string, const AppManifest*> manifests;
+    std::unordered_map<uint32_t, AppInstanceRecord> instances;
+    uint32_t next_instance_id = 1;
+    Mutex mutex {};
+
+    AppLedger() { mutex_construct(&mutex); }
+    ~AppLedger() { mutex_destruct(&mutex); }
+};
+
+inline AppLedger& app_ledger() {
+    static AppLedger ledger;
+    return ledger;
+}
+
+/**
+ * Frees a deep-copied argv previously built by app_manager_start_with_parameters()/app_manager_start_for_result():
+ * each individually heap-allocated string, then the array itself. Safe to call with count == 0  values == nullptr (no-op).
+ */
+inline void app_ledger_free_arguments(int count, char** values) {
+    if (values == nullptr) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        delete[] values[i];
+    }
+    delete[] values;
+}

Modules/app-module/private/app/private/app_metadata_parsing_internal.h

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/metadata.h>
+
+#include <map>
+#include <string>
+
+/** Shared helpers + per-format parsers for app_metadata_parse() (source/app_metadata_parsing.cpp)
+ * - split out like the old tt::app manifest parser (AppManifestParsing/V1/V2.cpp) that this is
+ * modelled on, one file per format plus a shared dispatcher. */
+
+bool app_metadata_get_value(const std::map<std::string, std::string>& properties, const std::string& key, std::string& out_value);
+
+bool app_metadata_is_valid_format_version(const std::string& version);
+bool app_metadata_is_valid_id(const std::string& id);
+bool app_metadata_is_valid_name(const std::string& name);
+bool app_metadata_is_valid_version_name(const std::string& version);
+bool app_metadata_is_valid_version_code(const std::string& version);
+
+/** Copies @a value into @a dest (a fixed-size buffer of @a dest_size bytes, including the NULL
+ * terminator) if it fits.
+ * @retval false @a value doesn't fit in @a dest_size bytes - @a dest is left untouched */
+bool app_metadata_copy_bounded(char* dest, size_t dest_size, const std::string& value);
+
+/** Parses a V1 (sectioned INI, e.g. "[app]versionName=...") manifest map into @a out_metadata. */
+bool app_metadata_parse_v1(const std::map<std::string, std::string>& properties, struct AppMetadata& out_metadata);
+
+/** Parses a V2 (flat dot-notation, e.g. "app.version.name=...") manifest map into @a out_metadata. */
+bool app_metadata_parse_v2(const std::map<std::string, std::string>& properties, struct AppMetadata& out_metadata);

Modules/app-module/private/app/private/app_scheduler.h

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/manifest.h>
+
+#include <tactility/error.h>
+
+/**
+ * Owns per-app task lifecycle on behalf of app_manager_*(). AppLoaderApi implementations
+ * stay task-agnostic; all of xTaskCreate()/vTaskDelete() happens here, as a plain FreeRTOS task
+ * (not TactilityKernel's Thread wrapper). Every app instance gets its own dedicated task for its
+ * entire lifetime - no task is ever reused for a different instance.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Loads and starts an app instance: spawns a dedicated task that calls
+ * AppLoaderApi::load()/run(), marking the instance ACTIVE for the duration of run().
+ * @param[in] app_instance_id id already allocated in the ledger for this instance
+ * @param[in] location the location of the app
+ * @param[in] argc the amount of arguments to pass to the app's main function
+ * @param[in] argv the array of arguments to pass to the app's main function - ownership is
+ * taken by the scheduler regardless of outcome (freed once the spawned task's run() returns, or
+ * immediately on a failure to start it)
+ */
+error_t app_scheduler_start(AppInstanceId app_instance_id, struct AppLocation location, int argc, char* argv[]);
+
+/**
+ * Permanently stops an app instance (APP_EVENT_CLOSE if it was running), bound-waits for its
+ * task to exit, and removes it from the ledger.
+ */
+error_t app_scheduler_stop(AppInstanceId app_instance_id, TickType_t join_timeout);
+
+// app_scheduler_current_app_id() is public - see app/scheduler.h.
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/source/app_install.cpp

@@ -0,0 +1,413 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/install.h>
+
+#include <app/manager.h>
+#include <app/metadata.h>
+
+#include <app/private/app_fs.h>
+#include <app/private/app_ledger.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/filesystem/file_mutex.h>
+#include <tactility/log.h>
+#include <tactility/paths.h>
+
+#include <minitar.h>
+
+#include <cerrno>
+#include <cstdio>
+#include <cstring>
+#include <dirent.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+constexpr auto* TAG = "app_install";
+
+namespace {
+
+// region Filesystem helpers (app-module may not depend upward on Tactility::file - see
+// app_metadata_parsing.cpp for the same constraint applied to properties-file loading)
+
+std::string last_path_segment(const std::string& path) {
+    auto index = path.find_last_of('/');
+    return index == std::string::npos ? path : path.substr(index + 1);
+}
+
+// mkdir -p.
+bool ensure_directory(const std::string& path) {
+    if (path.empty() || app_fs_is_directory(path)) {
+        return true;
+    }
+
+    FileMutex mutex {};
+    file_mutex_get(&mutex, path.c_str());
+    file_mutex_lock(&mutex);
+    bool created = mkdir(path.c_str(), 0777) == 0 || errno == EEXIST;
+    file_mutex_unlock(&mutex);
+    if (!created) {
+        return false;
+    }
+
+    return app_fs_is_directory(path);
+}
+
+bool ensure_directory_recursive(const std::string& path) {
+    for (size_t index = path.find('/', 1); index != std::string::npos; index = path.find('/', index + 1)) {
+        if (!ensure_directory(path.substr(0, index))) {
+            return false;
+        }
+    }
+    return ensure_directory(path);
+}
+
+bool delete_recursively(const std::string& path) {
+    LOG_D(TAG, "Deleting %s...", path.c_str());
+    if (path.empty() || path == "/" || path == "." || path == "..") {
+        return true;
+    }
+
+    if (app_fs_is_directory(path)) {
+        LOG_D(TAG, "Deleting dir %s", path.c_str());
+
+        FileMutex file_mutex;
+        file_mutex_get(&file_mutex, path.c_str());
+        file_mutex_lock(&file_mutex);
+
+        DIR* dir = opendir(path.c_str());
+        if (dir == nullptr) {
+            LOG_E(TAG, "Failed to scan directory %s", path.c_str());
+            file_mutex_unlock(&file_mutex);
+            return false;
+        }
+
+        bool success = true;
+        dirent* entry;
+        while (success && (entry = readdir(dir)) != nullptr) {
+            if (std::strcmp(entry->d_name, ".") == 0 || std::strcmp(entry->d_name, "..") == 0) {
+                continue;
+            }
+            success = delete_recursively(path + "/" + entry->d_name);
+        }
+        closedir(dir);
+
+        if (!success) {
+            file_mutex_unlock(&file_mutex);
+            return false;
+        }
+
+        bool result = rmdir(path.c_str()) == 0;
+        file_mutex_unlock(&file_mutex);
+        return result;
+    }
+
+    if (app_fs_is_file(path)) {
+        LOG_D(TAG, "Deleting file %s", path.c_str());
+        FileMutex mutex {};
+        file_mutex_get(&mutex, path.c_str());
+        file_mutex_lock(&mutex);
+        bool result = remove(path.c_str()) == 0;
+        file_mutex_unlock(&mutex);
+        return result;
+    }
+
+    LOG_D(TAG, "Deleting done");
+    return true;
+}
+
+bool get_app_install_directory(std::string& out_path) {
+    char root[192];
+    if (paths_get_user_data_path(root, sizeof(root)) != ERROR_NONE) {
+        return false;
+    }
+    out_path = std::string(root) + "/app";
+    return true;
+}
+
+// endregion
+
+// region Tar extraction (ported from the old Tactility::app AppInstall.cpp)
+
+bool untar_file(minitar* archive, const minitar_entry* entry, const std::string& destination_path) {
+    auto absolute_path = destination_path + "/" + entry->metadata.path;
+    if (!ensure_directory_recursive(destination_path)) {
+        LOG_E(TAG, "Can't find or create directory %s", destination_path.c_str());
+        return false;
+    }
+
+    if (!minitar_read_contents_to_file(archive, entry, absolute_path.c_str())) {
+        LOG_E(TAG, "Failed to write data to %s", absolute_path.c_str());
+        return false;
+    }
+
+    // Note: fchmod() doesn't exist on ESP-IDF and chmod() does nothing on that platform.
+    chmod(absolute_path.c_str(), entry->metadata.mode);
+
+    return true;
+}
+
+bool untar_directory(const minitar_entry* entry, const std::string& destination_path) {
+    return ensure_directory_recursive(destination_path + "/" + entry->metadata.path);
+}
+
+bool untar(const std::string& tar_path, const std::string& destination_path) {
+    minitar archive {};
+    if (minitar_open(tar_path.c_str(), &archive) != 0) {
+        LOG_E(TAG, "Failed to open %s", tar_path.c_str());
+        return false;
+    }
+
+    bool success = true;
+    minitar_entry entry {};
+    while (minitar_read_entry(&archive, &entry) == 0) {
+        LOG_I(TAG, "Extracting %s", entry.metadata.path);
+        if (entry.metadata.type == MTAR_DIRECTORY) {
+            if (std::strcmp(entry.metadata.name, ".") == 0 || std::strcmp(entry.metadata.name, "..") == 0 || std::strcmp(entry.metadata.name, "/") == 0) {
+                continue;
+            }
+            success = untar_directory(&entry, destination_path);
+        } else if (entry.metadata.type == MTAR_REGULAR) {
+            success = untar_file(&archive, &entry, destination_path);
+        } else {
+            LOG_E(TAG, "Unsupported entry type: %d", static_cast<int>(entry.metadata.type));
+            success = false;
+        }
+
+        if (!success) {
+            LOG_E(TAG, "Failed to extract %s", entry.metadata.path);
+            break;
+        }
+    }
+
+    minitar_close(&archive);
+    return success;
+}
+
+// endregion
+
+// region Installed-app registry: owns the AppManifest (and its id/name/path strings) that
+// app_manager's ledger only keeps a non-owning pointer to (see app_manager_add()'s contract).
+
+struct InstalledAppRecord {
+    std::string id;
+    std::string name;
+    std::string path;
+    AppManifest manifest {};
+};
+
+struct InstallRegistry {
+    std::unordered_map<std::string, std::unique_ptr<InstalledAppRecord>> apps;
+    Mutex mutex {};
+
+    InstallRegistry() { mutex_construct(&mutex); }
+};
+
+InstallRegistry& install_registry() {
+    static InstallRegistry registry;
+    return registry;
+}
+
+// Registers @a app_dir_path (already confirmed to hold a valid manifest.properties, parsed into
+// @a metadata) with app_manager_add(), taking ownership of its id/name/path strings.
+// @warning Caller must hold install_registry().mutex, and must have already ensured
+// @a metadata.app_id isn't already registered (app_manager_add() rejects duplicates, but the
+// InstalledAppRecord for the earlier registration would leak since this always inserts fresh).
+error_t register_installed_app_locked(const std::string& app_dir_path, const AppMetadata& metadata) {
+    auto& registry = install_registry();
+
+    auto record = std::make_unique<InstalledAppRecord>();
+    record->id = metadata.app_id;
+    record->name = metadata.app_name;
+    record->path = app_dir_path;
+    record->manifest = AppManifest {
+        .id = record->id.c_str(),
+        .name = record->name.c_str(),
+        .category = APP_CATEGORY_USER,
+        .location = { APP_LOCATION_PATH, const_cast<char*>(record->path.c_str()) },
+        .flags = 0,
+    };
+
+    // Belt-and-braces: app_install()'s earlier app_manager_remove() call is meant to have
+    // already cleared any stale registration for this id (e.g. left over from
+    // app_manager_install_path_scan()'s separate registry), but that call happens before the
+    // tarball is even extracted - remove once more, right before add, so a duplicate id can
+    // never turn a filesystem-level install success into a reported failure.
+    app_manager_remove(record->id.c_str());
+
+    error_t add_result = app_manager_add(&record->manifest);
+    if (add_result != ERROR_NONE) {
+        LOG_E(TAG, "Failed to register app '%s': %s", record->id.c_str(), error_to_string(add_result));
+        return add_result;
+    }
+
+    registry.apps[record->id] = std::move(record);
+    return ERROR_NONE;
+}
+
+// Stops every currently-running instance of @a manifest. Collects matching instance ids while
+// holding the ledger lock, then calls app_manager_stop() on each after releasing it - that call
+// bound-joins the instance's thread, which must not happen while the ledger mutex (also taken by
+// the instance's own thread_main()) is held, or the two threads would deadlock each other.
+void stop_all_instances_of(const AppManifest* manifest) {
+    std::vector<uint32_t> instance_ids;
+
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    for (const auto& [id, record]: ledger.instances) {
+        if (record.manifest == manifest) {
+            instance_ids.push_back(id);
+        }
+    }
+    mutex_unlock(&ledger.mutex);
+
+    for (uint32_t id: instance_ids) {
+        app_manager_stop(id);
+    }
+}
+
+// Caller must already hold install_registry().mutex
+error_t uninstall_locked(const std::string& app_id) {
+    auto& registry = install_registry();
+    auto iterator = registry.apps.find(app_id);
+    if (iterator == registry.apps.end()) {
+        return ERROR_NOT_FOUND;
+    }
+
+    stop_all_instances_of(&iterator->second->manifest);
+    app_manager_remove(app_id.c_str());
+    delete_recursively(iterator->second->path);
+    registry.apps.erase(iterator);
+
+    return ERROR_NONE;
+}
+
+// endregion
+
+} // namespace
+
+extern "C" {
+
+error_t app_get_install_path(const char* app_id, char* path, size_t path_size) {
+    if (path_size == 0) {
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    path[0] = '\0';
+
+    std::string app_parent_path;
+    if (!get_app_install_directory(app_parent_path)) {
+        return ERROR_NOT_FOUND;
+    }
+
+    int written = std::snprintf(path, path_size, "%s/%s", app_parent_path.c_str(), app_id);
+    if (written < 0 || static_cast<size_t>(written) >= path_size) {
+        path[0] = '\0';
+        return ERROR_BUFFER_OVERFLOW;
+    }
+
+    return ERROR_NONE;
+}
+
+error_t app_install(const char* source_path) {
+    LOG_I(TAG, "Installing app from %s", source_path);
+
+    std::string app_parent_path;
+    if (!get_app_install_directory(app_parent_path)) {
+        return ERROR_NOT_FOUND;
+    }
+
+    if (!ensure_directory_recursive(app_parent_path)) {
+        LOG_E(TAG, "Failed to create %s", app_parent_path.c_str());
+        return ERROR_NOT_FOUND;
+    }
+
+    auto staging_path = app_parent_path + "/" + last_path_segment(source_path);
+    delete_recursively(staging_path);
+
+    FileMutex target_mutex {};
+    file_mutex_get(&target_mutex, app_parent_path.c_str());
+    FileMutex source_mutex {};
+    file_mutex_get(&source_mutex, source_path);
+
+    file_mutex_lock(&target_mutex);
+    file_mutex_lock(&source_mutex);
+    bool untar_success = untar(source_path, staging_path);
+    file_mutex_unlock(&source_mutex);
+    file_mutex_unlock(&target_mutex);
+
+    if (!untar_success) {
+        LOG_E(TAG, "Failed to extract %s", source_path);
+        delete_recursively(staging_path);
+        return ERROR_NOT_FOUND;
+    }
+
+    auto manifest_path = staging_path + "/manifest.properties";
+    if (!app_fs_is_file(manifest_path)) {
+        LOG_E(TAG, "Manifest not found at %s", manifest_path.c_str());
+        delete_recursively(staging_path);
+        return ERROR_INVALID_ARGUMENT;
+    }
+
+    AppMetadata metadata {};
+    if (app_metadata_parse(manifest_path.c_str(), &metadata) != ERROR_NONE) {
+        LOG_E(TAG, "Install failed: invalid manifest");
+        delete_recursively(staging_path);
+        return ERROR_INVALID_ARGUMENT;
+    }
+
+    auto& registry = install_registry();
+    mutex_lock(&registry.mutex);
+
+    // Replace any previous install of this app id (mirrors the old install()'s "already
+    // running/present" handling). uninstall_locked() only clears app_install.cpp's own
+    // registry - the same app id may instead be registered by app_manager_install_path_scan()
+    // (manager.cpp's separate registry, scanning this same directory tree), which
+    // uninstall_locked() doesn't know about. Clear the app-manager registration unconditionally
+    // too, or app_manager_add() below rejects the re-add as a duplicate.
+    uninstall_locked(metadata.app_id);
+
+    error_t remove_result = app_manager_remove(metadata.app_id);
+    if (remove_result != ERROR_NONE && remove_result != ERROR_NOT_FOUND) {
+        LOG_E(TAG, "Install failed: failed to remove existing installation");
+        mutex_unlock(&registry.mutex);
+        delete_recursively(staging_path);
+        return ERROR_RESOURCE;
+    }
+
+    auto final_path = app_parent_path + "/" + metadata.app_id;
+    delete_recursively(final_path);
+
+    file_mutex_lock(&target_mutex);
+    bool rename_success = rename(staging_path.c_str(), final_path.c_str()) == 0;
+    file_mutex_unlock(&target_mutex);
+
+    if (!rename_success) {
+        LOG_E(TAG, "Failed to rename \"%s\" to \"%s\"", staging_path.c_str(), final_path.c_str());
+        delete_recursively(staging_path);
+        mutex_unlock(&registry.mutex);
+        return ERROR_NOT_FOUND;
+    }
+
+    // Only remaining failure mode is a duplicate id - can't happen, uninstall_locked() above
+    // already removed any previous registration for this exact id.
+    error_t add_result = register_installed_app_locked(final_path, metadata);
+    mutex_unlock(&registry.mutex);
+
+    return add_result;
+}
+
+error_t app_uninstall(const char* app_id) {
+    LOG_I(TAG, "Uninstalling app %s", app_id);
+
+    auto& registry = install_registry();
+    mutex_lock(&registry.mutex);
+    error_t result = uninstall_locked(app_id);
+    mutex_unlock(&registry.mutex);
+
+    return result;
+}
+
+} // extern "C"

Modules/app-module/source/app_internal_loader.cpp

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/loader.h>
+#include <app/manifest.h>
+
+#include <service/instance.h>
+#include <service/manager.h>
+
+namespace {
+
+error_t api_load(AppLocation location, AppRuntime* out_runtime) {
+    if (location.type != APP_LOCATION_MEMORY) {
+        return ERROR_NOT_SUPPORTED;
+    }
+
+    *out_runtime = location.location;
+    return ERROR_NONE;
+}
+
+int32_t api_run(AppRuntime runtime, uint32_t app_instance_id, int argc, char* argv[]) {
+    auto entry = reinterpret_cast<AppMainFn>(runtime);
+    return entry(app_instance_id, argc, argv);
+}
+
+void api_unload(AppRuntime /*unused*/) {
+}
+
+AppLoaderApi memory_loader_api = {
+    .load = api_load,
+    .run = api_run,
+    .unload = api_unload,
+};
+
+void* create_service(const ServiceManifest*) {
+    return &memory_loader_api;
+}
+
+void destroy_service(const ServiceManifest*, void*) {
+}
+
+} // namespace
+
+ServiceManifest app_internal_loader_service_manifest = {
+    .id = APP_LOADER_MEMORY_SERVICE_ID,
+    .create_service = create_service,
+    .destroy_service = destroy_service,
+    .on_start = nullptr,
+    .on_stop = nullptr,
+};

Modules/app-module/source/app_metadata_parsing.cpp

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+#include "tactility/filesystem/file_mutex.h"
+
+
+#include <app/metadata.h>
+
+#include <app/private/app_metadata_parsing_internal.h>
+
+#include <tactility/log.h>
+
+#include <cctype>
+#include <cstring>
+#include <fstream>
+#include <map>
+#include <string>
+
+constexpr auto* TAG = "app_metadata";
+
+namespace {
+
+std::string trim(const std::string& value) {
+    constexpr auto* whitespace = " \t\r\n";
+    auto start = value.find_first_not_of(whitespace);
+    if (start == std::string::npos) {
+        return "";
+    }
+    auto end = value.find_last_not_of(whitespace);
+    return value.substr(start, end - start + 1);
+}
+
+bool validate_string(const std::string& value, bool (*is_valid_char)(char)) {
+    for (char c: value) {
+        if (!is_valid_char(c)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** manifest.properties format: "key=value" lines, "[section]" lines prefix every following key
+ * until the next section, "#" lines are comments, blank lines are skipped. Deliberately a local,
+ * minimal re-implementation rather than depending on Tactility's file::loadPropertiesFile() -
+ * app-module (like every other kernel module) may not depend upward on the Tactility layer. */
+bool load_properties(const std::string& path, std::map<std::string, std::string>& out_properties, std::string& out_first_line) {
+    FileMutex mutex;
+    file_mutex_get(&mutex, path.c_str());
+    file_mutex_lock(&mutex);
+
+    std::ifstream file(path);
+    if (!file.is_open()) {
+        file_mutex_unlock(&mutex);
+        return false;
+    }
+
+    std::string line;
+    std::string section_prefix;
+    bool got_first_line = false;
+    while (std::getline(file, line)) {
+        auto trimmed_line = trim(line);
+
+        if (trimmed_line.empty() || trimmed_line.starts_with("#")) {
+            continue;
+        }
+
+        if (!got_first_line) {
+            out_first_line = trimmed_line;
+            got_first_line = true;
+        }
+
+        if (trimmed_line.starts_with("[")) {
+            section_prefix = trimmed_line;
+            continue;
+        }
+
+        auto separator_index = trimmed_line.find('=');
+        if (separator_index == std::string::npos) {
+            LOG_E(TAG, "Failed to parse manifest line (skipped): %s", trimmed_line.c_str());
+            continue;
+        }
+
+        auto key = section_prefix + trim(trimmed_line.substr(0, separator_index));
+        auto value = trim(trimmed_line.substr(separator_index + 1));
+        out_properties[key] = value;
+    }
+
+    file_mutex_unlock(&mutex);
+    return true;
+}
+
+} // namespace
+
+bool app_metadata_get_value(const std::map<std::string, std::string>& properties, const std::string& key, std::string& out_value) {
+    const auto iterator = properties.find(key);
+    if (iterator == properties.end()) {
+        LOG_E(TAG, "Failed to find %s in manifest", key.c_str());
+        return false;
+    }
+    out_value = iterator->second;
+    return true;
+}
+
+bool app_metadata_is_valid_format_version(const std::string& version) {
+    return !version.empty() && validate_string(version, [](char c) {
+        return std::isalnum(static_cast<unsigned char>(c)) != 0 || c == '.';
+    });
+}
+
+bool app_metadata_is_valid_id(const std::string& id) {
+    return id.size() >= 5 && id.size() <= APP_METADATA_APP_ID_LENGTH && validate_string(id, [](char c) {
+        return std::isalnum(static_cast<unsigned char>(c)) != 0 || c == '.';
+    });
+}
+
+bool app_metadata_is_valid_name(const std::string& name) {
+    return name.size() >= 2 && name.size() <= APP_METADATA_APP_NAME_LENGTH && validate_string(name, [](char c) {
+        return std::isalnum(static_cast<unsigned char>(c)) != 0 || c == ' ' || c == '-';
+    });
+}
+
+bool app_metadata_is_valid_version_name(const std::string& version) {
+    return !version.empty() && version.size() <= APP_METADATA_APP_VERSION_NAME_LENGTH && validate_string(version, [](char c) {
+        return std::isalnum(static_cast<unsigned char>(c)) != 0 || c == '.' || c == '-' || c == '_';
+    });
+}
+
+bool app_metadata_is_valid_version_code(const std::string& version) {
+    // 20 digits is the maximum decimal width of uint64_t.
+    return !version.empty() && version.size() <= 20 && validate_string(version, [](char c) {
+        return std::isdigit(static_cast<unsigned char>(c)) != 0;
+    });
+}
+
+bool app_metadata_copy_bounded(char* dest, size_t dest_size, const std::string& value) {
+    if (value.size() >= dest_size) {
+        return false;
+    }
+    memcpy(dest, value.c_str(), value.size() + 1);
+    return true;
+}
+
+error_t app_metadata_parse(const char* path, struct AppMetadata* out_metadata) {
+    LOG_I(TAG, "Parsing manifest %s", path);
+
+    std::map<std::string, std::string> properties;
+    std::string first_line;
+    if (!load_properties(path, properties, first_line)) {
+        LOG_E(TAG, "Failed to load manifest at %s", path);
+        return ERROR_NOT_FOUND;
+    }
+
+    // The V1 format's first line is always the literal "[manifest]" section header; V2 files are
+    // flat from the first line onward.
+    bool is_v1_format = first_line == "[manifest]";
+    bool success = is_v1_format
+        ? app_metadata_parse_v1(properties, *out_metadata)
+        : app_metadata_parse_v2(properties, *out_metadata);
+
+    return success ? ERROR_NONE : ERROR_INVALID_ARGUMENT;
+}

Modules/app-module/source/app_metadata_parsing_v1.cpp

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/metadata.h>
+#include <app/private/app_metadata_parsing_internal.h>
+
+#include <charconv>
+
+#include <tactility/log.h>
+
+constexpr auto* TAG = "app_metadata_v1";
+
+bool app_metadata_parse_v1(const std::map<std::string, std::string>& properties, AppMetadata& out_metadata) {
+    // [manifest]
+
+    std::string format_version;
+    if (!app_metadata_get_value(properties, "[manifest]version", format_version)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_format_version(format_version)) {
+        LOG_E(TAG, "Invalid version");
+        return false;
+    }
+
+    // [app]
+
+    std::string id;
+    if (!app_metadata_get_value(properties, "[app]id", id)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_id(id)) {
+        LOG_E(TAG, "Invalid app id");
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.app_id, sizeof(out_metadata.app_id), id)) {
+        LOG_E(TAG, "App id too long");
+        return false;
+    }
+
+    std::string name;
+    if (!app_metadata_get_value(properties, "[app]name", name)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_name(name)) {
+        LOG_E(TAG, "Invalid app name");
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.app_name, sizeof(out_metadata.app_name), name)) {
+        LOG_E(TAG, "App name too long");
+        return false;
+    }
+
+    std::string version_name;
+    if (!app_metadata_get_value(properties, "[app]versionName", version_name)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_version_name(version_name)) {
+        LOG_E(TAG, "Invalid app version name");
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.app_version_name, sizeof(out_metadata.app_version_name), version_name)) {
+        LOG_E(TAG, "App version name too long");
+        return false;
+    }
+
+    std::string version_code_string;
+    if (!app_metadata_get_value(properties, "[app]versionCode", version_code_string)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_version_code(version_code_string)) {
+        LOG_E(TAG, "Invalid app version code");
+        return false;
+    }
+
+    uint64_t version_code = 0;
+    const auto* first = version_code_string.data();
+    const auto* last = first + version_code_string.size();
+    if (std::from_chars(first, last, version_code).ec != std::errc {}) {
+        LOG_E(TAG, "App version code out of range");
+        return false;
+    }
+    out_metadata.app_version_code = version_code;    // [target]
+
+    std::string target_sdk;
+    if (!app_metadata_get_value(properties, "[target]sdk", target_sdk)) {
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.target_sdk, sizeof(out_metadata.target_sdk), target_sdk)) {
+        LOG_E(TAG, "Target sdk too long");
+        return false;
+    }
+
+    return true;
+}

Modules/app-module/source/app_metadata_parsing_v2.cpp

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/metadata.h>
+#include <app/private/app_metadata_parsing_internal.h>
+
+#include <charconv>
+
+#include <tactility/log.h>
+
+constexpr auto* TAG = "app_metadata_v2";
+
+bool app_metadata_parse_v2(const std::map<std::string, std::string>& properties, AppMetadata& out_metadata) {
+    // manifest
+
+    std::string format_version;
+    if (!app_metadata_get_value(properties, "manifest.version", format_version)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_format_version(format_version)) {
+        LOG_E(TAG, "Invalid version");
+        return false;
+    }
+
+    // app
+
+    std::string id;
+    if (!app_metadata_get_value(properties, "app.id", id)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_id(id)) {
+        LOG_E(TAG, "Invalid app id");
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.app_id, sizeof(out_metadata.app_id), id)) {
+        LOG_E(TAG, "App id too long");
+        return false;
+    }
+
+    std::string name;
+    if (!app_metadata_get_value(properties, "app.name", name)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_name(name)) {
+        LOG_E(TAG, "Invalid app name");
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.app_name, sizeof(out_metadata.app_name), name)) {
+        LOG_E(TAG, "App name too long");
+        return false;
+    }
+
+    std::string version_name;
+    if (!app_metadata_get_value(properties, "app.version.name", version_name)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_version_name(version_name)) {
+        LOG_E(TAG, "Invalid app version name");
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.app_version_name, sizeof(out_metadata.app_version_name), version_name)) {
+        LOG_E(TAG, "App version name too long");
+        return false;
+    }
+
+    std::string version_code_string;
+    if (!app_metadata_get_value(properties, "app.version.code", version_code_string)) {
+        return false;
+    }
+
+    if (!app_metadata_is_valid_version_code(version_code_string)) {
+        LOG_E(TAG, "Invalid app version code");
+        return false;
+    }
+
+    uint64_t version_code = 0;
+    const auto* first = version_code_string.data();
+    const auto* last = first + version_code_string.size();
+    if (std::from_chars(first, last, version_code).ec != std::errc {}) {
+        LOG_E(TAG, "App version code out of range");
+        return false;
+    }
+    out_metadata.app_version_code = version_code; // [target]
+
+    // target
+
+    std::string target_sdk;
+    if (!app_metadata_get_value(properties, "target.sdk", target_sdk)) {
+        return false;
+    }
+
+    if (!app_metadata_copy_bounded(out_metadata.target_sdk, sizeof(out_metadata.target_sdk), target_sdk)) {
+        LOG_E(TAG, "Target sdk too long");
+        return false;
+    }
+
+    return true;
+}

Modules/app-module/source/app_paths.cpp

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <app/paths.h>
+#include <tactility/paths.h>
+
+#include <cstdio>
+
+extern "C" {
+
+error_t app_paths_get_user_data_directory(const char* app_id, char* out_path, size_t out_path_size) {
+    char root[192];
+    error_t error = paths_get_user_data_path(root, sizeof(root));
+    if (error != ERROR_NONE) {
+        return error;
+    }
+    int written = std::snprintf(out_path, out_path_size, "%s/app/%s", root, app_id);
+    if (written < 0 || (size_t)written >= out_path_size) {
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    return ERROR_NONE;
+}
+
+error_t app_paths_get_user_data_path(const char* app_id, const char* child_path, char* out_path, size_t out_path_size) {
+    char directory[224];
+    error_t error = app_paths_get_user_data_directory(app_id, directory, sizeof(directory));
+    if (error != ERROR_NONE) {
+        return error;
+    }
+    int written = std::snprintf(out_path, out_path_size, "%s/%s", directory, child_path);
+    if (written < 0 || (size_t)written >= out_path_size) {
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    return ERROR_NONE;
+}
+
+error_t app_paths_get_assets_directory(const char* app_id, char* out_path, size_t out_path_size) {
+    char directory[224];
+    error_t error = app_paths_get_user_data_directory(app_id, directory, sizeof(directory));
+    if (error != ERROR_NONE) {
+        return error;
+    }
+    int written = std::snprintf(out_path, out_path_size, "%s/assets", directory);
+    if (written < 0 || (size_t)written >= out_path_size) {
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    return ERROR_NONE;
+}
+
+error_t app_paths_get_assets_path(const char* app_id, const char* child_path, char* out_path, size_t out_path_size) {
+    char directory[224];
+    error_t error = app_paths_get_assets_directory(app_id, directory, sizeof(directory));
+    if (error != ERROR_NONE) {
+        return error;
+    }
+    int written = std::snprintf(out_path, out_path_size, "%s/%s", directory, child_path);
+    if (written < 0 || (size_t)written >= out_path_size) {
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    return ERROR_NONE;
+}
+
+} // extern "C"

Modules/app-module/source/app_scheduler.cpp

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/private/app_ledger.h>
+#include <app/private/app_scheduler.h>
+#include <app/event.h>
+#include <app/instance.h>
+#include <app/loader.h>
+#include <app/scheduler.h>
+
+#include <service/instance.h>
+#include <service/manager.h>
+
+#include <tactility/error.h>
+#include <tactility/log.h>
+
+#include <cstdint>
+#include <cstdio>
+#include <new>
+
+constexpr auto* TAG = "app_scheduler";
+
+// Slot 0 is reserved by ESP-IDF's pthread API (see TactilityKernel's Thread wrapper for the
+// same convention/comment) - app tasks use slot 1 to stash their own app_instance_id, so any
+// code running on an app's own task can retrieve it via app_scheduler_current_app_id() without
+// needing it threaded through as a parameter.
+constexpr size_t APP_INSTANCE_ID_THREAD_SLOT_INDEX = 1;
+
+// Matches TactilityKernel's Thread wrapper's THREAD_PRIORITY_NORMAL.
+constexpr UBaseType_t APP_TASK_PRIORITY = 4;
+
+namespace {
+
+struct TaskContext {
+    const AppLoaderApi* loader;
+    void* runtime;
+    AppInstanceId app_instance_id;
+    int argc;
+    char** argv;
+    AppCompletionSignal* completion;
+};
+
+void set_state(AppInstanceId app_instance_id, AppInstanceState state) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    if (iterator != ledger.instances.end()) {
+        iterator->second.state = state;
+    }
+    mutex_unlock(&ledger.mutex);
+}
+
+void set_task(AppInstanceId app_instance_id, TaskHandle_t task) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    if (iterator != ledger.instances.end()) {
+        iterator->second.task = task;
+    }
+    mutex_unlock(&ledger.mutex);
+}
+
+void set_completion(AppInstanceId app_instance_id, AppCompletionSignal* completion) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    if (iterator != ledger.instances.end()) {
+        iterator->second.completion = completion;
+    }
+    mutex_unlock(&ledger.mutex);
+}
+
+// Takes a reference on app_instance_id's completion signal (see AppCompletionSignal), for the
+// caller to wait on. @return the signal to wait on, or NULL if the instance has already fully
+// finished (its ledger entry - and so its reference to the signal - is already gone) and so
+// there's nothing left to wait for, or if the instance is still starting up (start_internal()
+// in manager.cpp inserts the ledger entry before app_scheduler_start() has gotten as far as
+// set_completion() - `completion` is NULL for that whole window) and so there's nothing to
+// take a reference on yet.
+AppCompletionSignal* acquire_completion_signal(AppInstanceId app_instance_id) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    AppCompletionSignal* completion = nullptr;
+    if (iterator != ledger.instances.end() && iterator->second.completion != nullptr) {
+        completion = iterator->second.completion;
+        completion->refcount++;
+    }
+    mutex_unlock(&ledger.mutex);
+    return completion;
+}
+
+// Releases a reference taken by acquire_completion_signal(), deleting the signal (and its
+// semaphore) if this was the last one.
+void release_completion_signal(AppCompletionSignal* completion) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    bool should_delete = (--completion->refcount == 0);
+    mutex_unlock(&ledger.mutex);
+    if (should_delete) {
+        vSemaphoreDelete(completion->semaphore);
+        delete completion;
+    }
+}
+
+const char* loader_service_id_for(AppLocationType type) {
+    return (type == APP_LOCATION_MEMORY) ? APP_LOADER_MEMORY_SERVICE_ID : APP_LOADER_PATH_SERVICE_ID;
+}
+
+const AppLoaderApi* find_loader_api(AppLocationType type) {
+    ServiceInstance* instance = service_manager_find_instance(loader_service_id_for(type));
+    if (instance == nullptr) {
+        return nullptr;
+    }
+    return static_cast<const AppLoaderApi*>(service_instance_get_data(instance));
+}
+
+// If this instance was launched via app_manager_start_for_result(), delivers @a result (its
+// own AppMainFn/AppLoaderApi::run() return value) to its parent. No-op for a top-level instance
+// (parent_id == 0).
+void deliver_result_to_parent_if_any(AppInstanceId app_instance_id, int32_t result) {
+    auto& ledger = app_ledger();
+
+    AppInstanceId parent_id;
+    AppEvent event { .type = APP_EVENT_RESULT, .timestamp = 0, .result = {} };
+
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    if (iterator == ledger.instances.end()) {
+        mutex_unlock(&ledger.mutex);
+        return;
+    }
+    parent_id = iterator->second.parent_id;
+    event.result.launch_id = app_instance_id;
+    event.result.result = result;
+    mutex_unlock(&ledger.mutex);
+
+    if (parent_id != 0) {
+        app_event_emit(parent_id, &event);
+    }
+}
+
+void app_task_main(void* context) {
+    auto* ctx = static_cast<TaskContext*>(context);
+
+    check(pvTaskGetThreadLocalStoragePointer(nullptr, APP_INSTANCE_ID_THREAD_SLOT_INDEX) == nullptr);
+    vTaskSetThreadLocalStoragePointer(nullptr, APP_INSTANCE_ID_THREAD_SLOT_INDEX, reinterpret_cast<void*>(static_cast<uintptr_t>(ctx->app_instance_id)));
+
+    LOG_I(TAG, "Thread for %d started", ctx->app_instance_id);
+
+    set_state(ctx->app_instance_id, APP_INSTANCE_STATE_ACTIVE);
+
+    int32_t result = ctx->loader->run(ctx->runtime, ctx->app_instance_id, ctx->argc, ctx->argv);
+
+    vTaskSetThreadLocalStoragePointer(nullptr, APP_INSTANCE_ID_THREAD_SLOT_INDEX, nullptr);
+
+    ctx->loader->unload(ctx->runtime);
+
+    deliver_result_to_parent_if_any(ctx->app_instance_id, result);
+
+    // A safe default terminal marker for CLOSE (and any other exit): an app that calls
+    // app_manager_finish() already marked itself Stopped before returning, so this is a no-op
+    // for it - but it's still needed as the terminal marker for any other exit path.
+    set_state(ctx->app_instance_id, APP_INSTANCE_STATE_STOPPED);
+
+    app_ledger_free_arguments(ctx->argc, ctx->argv);
+
+    AppInstanceId app_instance_id = ctx->app_instance_id;
+    AppCompletionSignal* completion = ctx->completion;
+    delete ctx;
+
+    LOG_I(TAG, "Thread for %d finished", app_instance_id);
+
+    // Erase the ledger entry before self-deleting - see "Reap self-terminated app tasks":
+    // nothing else is guaranteed to ever call app_scheduler_stop() for this instance (the
+    // common case is the app just closing itself), so this can't wait for that to happen.
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    ledger.instances.erase(app_instance_id);
+    mutex_unlock(&ledger.mutex);
+
+    // Signal completion as the literal last action before this task ceases to exist, so
+    // app_scheduler_stop() can't observe "stopped" one step early - unlike watching the ledger
+    // entry disappear, this can only happen once the task is truly done running. A dedicated
+    // semaphore rather than this task's default FreeRTOS notification, since app_event.cpp's
+    // AppEventSubscription also uses that shared slot - an unrelated event (e.g. a child's
+    // APP_EVENT_RESULT) delivered to this same task could otherwise unblock a concurrent
+    // app_scheduler_stop() early.
+    xSemaphoreGive(completion->semaphore);
+    release_completion_signal(completion); // releases app_task_main()'s own reference
+
+    vTaskDelete(nullptr);
+}
+
+} // namespace
+
+extern "C" {
+
+error_t app_scheduler_start(AppInstanceId app_instance_id, AppLocation location, int argc, char* argv[]) {
+    const AppLoaderApi* loader = find_loader_api(location.type);
+    if (loader == nullptr) {
+        LOG_E(TAG, "No app loader is registered (service '%s' not found)", loader_service_id_for(location.type));
+        app_ledger_free_arguments(argc, argv);
+        return ERROR_NOT_FOUND;
+    }
+
+    void* runtime = nullptr;
+    error_t load_result = loader->load(location, &runtime);
+    if (load_result != ERROR_NONE) {
+        LOG_E(TAG, "Failed to load app: %s", error_to_string(load_result));
+        app_ledger_free_arguments(argc, argv);
+        return load_result;
+    }
+
+    auto* completion = new (std::nothrow) AppCompletionSignal();
+    if (completion == nullptr) {
+        LOG_E(TAG, "Failed to allocate app");
+        loader->unload(runtime);
+        app_ledger_free_arguments(argc, argv);
+        return ERROR_OUT_OF_MEMORY;
+    }
+    completion->semaphore = xSemaphoreCreateBinary();
+    if (completion->semaphore == nullptr) {
+        LOG_E(TAG, "Failed to allocate app");
+        delete completion;
+        loader->unload(runtime);
+        app_ledger_free_arguments(argc, argv);
+        return ERROR_OUT_OF_MEMORY;
+    }
+
+    auto* context = new (std::nothrow) TaskContext { loader, runtime, app_instance_id, argc, argv, completion };
+    if (context == nullptr) {
+        LOG_E(TAG, "Failed to allocate app");
+        vSemaphoreDelete(completion->semaphore);
+        delete completion;
+        loader->unload(runtime);
+        app_ledger_free_arguments(argc, argv);
+        return ERROR_OUT_OF_MEMORY;
+    }
+
+    char task_name[16];
+    snprintf(task_name, sizeof(task_name), "app_%lu", static_cast<unsigned long>(app_instance_id));
+
+    TaskHandle_t task_handle = nullptr;
+    // 8192 bytes -> stack depth in words, matching what TactilityKernel's Thread wrapper does with the stack size it's given.
+    // Created at idle priority so it can't preempt us before vTaskSuspend() below runs, then suspended immediately -
+    // the ledger must record the handle (set_task()) before the task can possibly observe or erase its own entry.
+    // (see app_scheduler_stop()'s liveness check and app_task_main()'s exit path)
+    BaseType_t create_result = xTaskCreate(app_task_main, task_name, 8192 / sizeof(StackType_t), context, tskIDLE_PRIORITY, &task_handle);
+    if (create_result != pdPASS) {
+        delete context;
+        vSemaphoreDelete(completion->semaphore);
+        delete completion;
+        loader->unload(runtime);
+        app_ledger_free_arguments(argc, argv);
+        return ERROR_OUT_OF_MEMORY;
+    }
+    vTaskSuspend(task_handle);
+
+    set_task(app_instance_id, task_handle);
+    set_completion(app_instance_id, completion);
+    vTaskPrioritySet(task_handle, APP_TASK_PRIORITY);
+    vTaskResume(task_handle);
+
+    return ERROR_NONE;
+}
+
+error_t app_scheduler_stop(AppInstanceId app_instance_id, TickType_t join_timeout) {
+    AppCompletionSignal* completion = acquire_completion_signal(app_instance_id);
+    if (completion != nullptr) {
+        AppEvent event { .type = APP_EVENT_CLOSE, .timestamp = 0, .result = {} };
+        app_event_emit(app_instance_id, &event);
+
+        // Blocks until app_task_main() gives this dedicated semaphore as the literal last thing it does before vTaskDelete().
+        // Uses aa dedicated semaphore rather than this task's default FreeRTOS notification because app_event.cpp's AppEventSubscription also uses that shared slot.
+        // An unrelated event (e.g. a different child's APP_EVENT_RESULT) delivered to this same task could otherwise unblock this early.
+        BaseType_t taken = xSemaphoreTake(completion->semaphore, join_timeout);
+        release_completion_signal(completion);
+
+        if (taken == pdFALSE) {
+            LOG_W(TAG, "App instance %u did not stop in time", app_instance_id);
+            return ERROR_TIMEOUT;
+        }
+    }
+
+    set_state(app_instance_id, APP_INSTANCE_STATE_STOPPED);
+
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    ledger.instances.erase(app_instance_id);
+    mutex_unlock(&ledger.mutex);
+
+    return ERROR_NONE;
+}
+
+AppInstanceId app_scheduler_current_app_id(void) {
+    void* value = pvTaskGetThreadLocalStoragePointer(nullptr, APP_INSTANCE_ID_THREAD_SLOT_INDEX);
+    return reinterpret_cast<uintptr_t>(value);
+}
+
+} // extern "C"

Modules/app-module/source/event.cpp

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/event.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/time.h>
+
+/**
+ * Intrusive singly-linked list of subscriptions, keyed by app_instance_id.
+ * Guarded by a single coarse-grained mutex, notifying a subscriber here never invokes caller code
+ * (just a struct copy and an xTaskNotifyGive), so there is no reentrancy concern requiring a snapshot-then-unlock dance.
+ */
+static AppEventSubscription* subscriptions = nullptr;
+
+struct AppEventMutex {
+    Mutex handle {};
+    AppEventMutex() { mutex_construct(&handle); }
+    ~AppEventMutex() { mutex_destruct(&handle); }
+};
+
+static AppEventMutex subscriptions_mutex;
+
+extern "C" {
+
+error_t app_event_subscribe(AppEventSubscription* sub) {
+    sub->task = xTaskGetCurrentTaskHandle();
+    sub->head = 0;
+    sub->count = 0;
+
+    mutex_lock(&subscriptions_mutex.handle);
+    sub->next = subscriptions;
+    subscriptions = sub;
+    mutex_unlock(&subscriptions_mutex.handle);
+
+    return ERROR_NONE;
+}
+
+error_t app_event_unsubscribe(AppEventSubscription* sub) {
+    error_t result = ERROR_NOT_FOUND;
+
+    mutex_lock(&subscriptions_mutex.handle);
+    for (AppEventSubscription** link = &subscriptions; *link != nullptr; link = &(*link)->next) {
+        if (*link == sub) {
+            *link = sub->next;
+            result = ERROR_NONE;
+            break;
+        }
+    }
+    mutex_unlock(&subscriptions_mutex.handle);
+
+    return result;
+}
+
+error_t app_event_emit(uint32_t app_instance_id, const AppEvent* event) {
+    AppEvent stamped_event = *event;
+    stamped_event.timestamp = get_micros_since_boot();
+
+    error_t result = ERROR_NOT_FOUND;
+
+    mutex_lock(&subscriptions_mutex.handle);
+    for (AppEventSubscription* sub = subscriptions; sub != nullptr; sub = sub->next) {
+        if (sub->app_instance_id != app_instance_id) {
+            continue;
+        }
+
+        if (sub->count >= APP_EVENT_QUEUE_CAPACITY) {
+            result = ERROR_RESOURCE;
+            continue;
+        }
+
+        uint8_t tail = (sub->head + sub->count) % APP_EVENT_QUEUE_CAPACITY;
+        sub->queue[tail] = stamped_event;
+        sub->count++;
+        if (result != ERROR_RESOURCE) {
+            result = ERROR_NONE;
+        }
+        xTaskNotifyGive(sub->task);
+    }
+    mutex_unlock(&subscriptions_mutex.handle);
+
+    return result;
+}
+
+static bool try_pop(AppEventSubscription* sub, AppEvent* out_event) {
+    mutex_lock(&subscriptions_mutex.handle);
+    bool has_event = sub->count > 0;
+    if (has_event) {
+        *out_event = sub->queue[sub->head];
+        sub->head = (sub->head + 1) % APP_EVENT_QUEUE_CAPACITY;
+        sub->count--;
+    }
+    mutex_unlock(&subscriptions_mutex.handle);
+    return has_event;
+}
+
+error_t app_event_await(AppEventSubscription* sub, AppEvent* out_event, TickType_t timeout) {
+    if (try_pop(sub, out_event)) {
+        // Drain any notification credit this (or an earlier) push accumulated on this task's
+        // FreeRTOS notification value: each app_event_emit() calls xTaskNotifyGive() regardless
+        // of whether the consumer takes this fast path or the blocking path below, so without
+        // this the credit would carry over and cause a future ulTaskNotifyTake() below to
+        // return immediately for a notification that was already accounted for here.
+        ulTaskNotifyTake(pdTRUE, 0);
+        return ERROR_NONE;
+    }
+
+    if (ulTaskNotifyTake(pdTRUE, timeout) == 0) {
+        return ERROR_TIMEOUT;
+    }
+
+    // Single-consumer by design (one task per subscription), so a wakeup implies the event
+    // this call was notified for is still there for us to pop.
+    return try_pop(sub, out_event) ? ERROR_NONE : ERROR_TIMEOUT;
+}
+
+} // extern "C"

Modules/app-module/source/manager.cpp

@@ -0,0 +1,337 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/manager.h>
+
+#include <app/metadata.h>
+
+#include <app/private/app_fs.h>
+#include <app/private/app_ledger.h>
+#include <app/private/app_scheduler.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/log.h>
+
+#include <algorithm>
+#include <cstring>
+#include <memory>
+#include <unordered_map>
+#include <vector>
+
+#define TAG "app_manager"
+
+extern "C" {
+
+error_t app_manager_add(const AppManifest* manifest) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    if (ledger.manifests.contains(manifest->id)) {
+        mutex_unlock(&ledger.mutex);
+        LOG_E(TAG, "Manifest with id '%s' is already registered", manifest->id);
+        return ERROR_INVALID_ARGUMENT;
+    }
+    ledger.manifests[manifest->id] = manifest;
+    mutex_unlock(&ledger.mutex);
+
+    return ERROR_NONE;
+}
+
+error_t app_manager_remove(const char* id) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.manifests.find(id);
+    if (iterator == ledger.manifests.end()) {
+        mutex_unlock(&ledger.mutex);
+        return ERROR_NOT_FOUND;
+    }
+    ledger.manifests.erase(iterator);
+    mutex_unlock(&ledger.mutex);
+
+    return ERROR_NONE;
+}
+
+const AppManifest* app_manager_find_manifest(const char* id) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.manifests.find(id);
+    const AppManifest* manifest = (iterator != ledger.manifests.end()) ? iterator->second : nullptr;
+    mutex_unlock(&ledger.mutex);
+    return manifest;
+}
+
+void app_manager_for_each_manifest(AppManifestVisitorFn visitor, void* context) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    for (auto& [id, manifest] : ledger.manifests) {
+        visitor(manifest, context);
+    }
+    mutex_unlock(&ledger.mutex);
+}
+
+namespace {
+
+// Deep-copies argv (argc <= 0 => NULL, matching "no parameters"). Caller passes the result to
+// app_scheduler_start(), which takes ownership regardless of outcome.
+char** copy_arguments(int argc, const char* const argv[]) {
+    if (argc <= 0) {
+        return nullptr;
+    }
+    auto* copy = new char*[argc + 1];
+    for (int i = 0; i < argc; i++) {
+        size_t length = strlen(argv[i]);
+        copy[i] = new char[length + 1];
+        memcpy(copy[i], argv[i], length + 1);
+    }
+    copy[argc] = nullptr;
+    return copy;
+}
+
+// Takes ownership of argv (already a deep copy, or NULL/argc==0) regardless of outcome -
+// app_scheduler_start() frees it on any failure path, and the spawned task frees it once its
+// run() returns.
+error_t start_internal(const char* id, AppInstanceId parent_instance_id, int argc, char* argv[], AppInstanceId* out_app_instance_id) {
+    const AppManifest* manifest = app_manager_find_manifest(id);
+    if (manifest == nullptr) {
+        app_ledger_free_arguments(argc, argv);
+        return ERROR_NOT_FOUND;
+    }
+
+    auto& ledger = app_ledger();
+
+    mutex_lock(&ledger.mutex);
+    AppInstanceId target_id = ledger.next_instance_id++;
+    AppInstanceRecord record { target_id, manifest, APP_INSTANCE_STATE_STARTING, nullptr };
+    record.parent_id = parent_instance_id;
+    ledger.instances[target_id] = record;
+    mutex_unlock(&ledger.mutex);
+
+    error_t result = app_scheduler_start(target_id, manifest->location, argc, argv);
+    if (result != ERROR_NONE) {
+        mutex_lock(&ledger.mutex);
+        ledger.instances.erase(target_id);
+        mutex_unlock(&ledger.mutex);
+        return result;
+    }
+
+    *out_app_instance_id = target_id;
+    return ERROR_NONE;
+}
+
+} // namespace
+
+error_t app_manager_start(const char* id, AppInstanceId* out_app_instance_id) {
+    return start_internal(id, 0, 0, nullptr, out_app_instance_id);
+}
+
+error_t app_manager_start_with_parameters(const char* id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id) {
+    return start_internal(id, 0, argc, copy_arguments(argc, argv), out_app_instance_id);
+}
+
+error_t app_manager_start_for_result(const char* id, AppInstanceId parent_instance_id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id) {
+    return start_internal(id, parent_instance_id, argc, copy_arguments(argc, argv), out_app_instance_id);
+}
+
+error_t app_manager_stop(AppInstanceId app_instance_id) {
+    return app_scheduler_stop(app_instance_id, pdMS_TO_TICKS(2000));
+}
+
+error_t app_manager_finish(AppInstanceId app_instance_id) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    if (iterator != ledger.instances.end()) {
+        iterator->second.state = APP_INSTANCE_STATE_STOPPED;
+    }
+    mutex_unlock(&ledger.mutex);
+    return ERROR_NONE;
+}
+
+AppInstanceState app_manager_get_state(AppInstanceId app_instance_id) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_instance_id);
+    AppInstanceState state = (iterator != ledger.instances.end()) ? iterator->second.state : APP_INSTANCE_STATE_STOPPED;
+    mutex_unlock(&ledger.mutex);
+    return state;
+}
+
+error_t app_manager_get_topmost_instance_id(AppInstanceId* out_app_instance_id) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    AppInstanceId topmost_id = 0;
+    for (auto& [instance_id, record] : ledger.instances) {
+        // Instance ids are handed out in increasing order (AppLedger::next_instance_id), so
+        // the highest Active id is also the most recently started one.
+        if (record.state == APP_INSTANCE_STATE_ACTIVE && instance_id > topmost_id) {
+            topmost_id = instance_id;
+        }
+    }
+    mutex_unlock(&ledger.mutex);
+
+    if (topmost_id == 0) {
+        return ERROR_NOT_FOUND;
+    }
+    *out_app_instance_id = topmost_id;
+    return ERROR_NONE;
+}
+
+error_t app_manager_get_topmost_app_id(char* buffer, size_t buffer_size) {
+    if (buffer_size == 0) {
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    buffer[0] = '\0';
+
+    AppInstanceId topmost_id = 0;
+    error_t result = app_manager_get_topmost_instance_id(&topmost_id);
+    if (result != ERROR_NONE) {
+        return result;
+    }
+
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(topmost_id);
+    const char* app_id = (iterator != ledger.instances.end()) ? iterator->second.manifest->id : nullptr;
+    mutex_unlock(&ledger.mutex);
+
+    if (app_id == nullptr) {
+        return ERROR_NOT_FOUND;
+    }
+
+    size_t length = strlen(app_id);
+    if (length >= buffer_size) {
+        buffer[0] = '\0';
+        return ERROR_BUFFER_OVERFLOW;
+    }
+    memcpy(buffer, app_id, length + 1);
+    return ERROR_NONE;
+}
+
+} // extern "C"
+
+namespace {
+
+// Owns the AppManifest (and its id/name/path strings) that app_manager_add() only keeps a
+// non-owning pointer to (see app_manager_add()'s contract), for manifests registered by
+// app_manager_install_path_scan() specifically - separate from app_install.cpp's own registry,
+// since scanning only ever adds/removes manifest registrations and never touches files on disk
+// or running instances (unlike app_install()/app_uninstall()).
+struct ScannedAppManifest {
+    std::string id;
+    std::string name;
+    std::string path;
+    AppManifest manifest {};
+};
+
+struct InstallPathRegistry {
+    std::vector<std::string> paths;
+    std::unordered_map<std::string, std::unique_ptr<ScannedAppManifest>> scanned;
+    Mutex mutex {};
+
+    InstallPathRegistry() { mutex_construct(&mutex); }
+};
+
+InstallPathRegistry& install_path_registry() {
+    static InstallPathRegistry registry;
+    return registry;
+}
+
+} // namespace
+
+extern "C" {
+
+error_t app_manager_install_path_add(const char* path) {
+    auto& registry = install_path_registry();
+    mutex_lock(&registry.mutex);
+    if (std::ranges::find(registry.paths, path) == registry.paths.end()) {
+        registry.paths.emplace_back(path);
+    }
+    mutex_unlock(&registry.mutex);
+    return ERROR_NONE;
+}
+
+void app_manager_install_path_scan(void) {
+    auto& registry = install_path_registry();
+
+    mutex_lock(&registry.mutex);
+    auto paths_copy = registry.paths;
+    mutex_unlock(&registry.mutex);
+
+    std::vector<std::string> found_app_dirs;
+    for (const auto& root : paths_copy) {
+        app_fs_list_direct_subdirectories(root, found_app_dirs);
+    }
+
+    // Snapshot of what's already registered, taken once so the rest of this scan can run without holding registry.mutex
+    mutex_lock(&registry.mutex);
+    std::unordered_map<std::string, std::string> known_paths; // id -> path
+    for (const auto& [id, record] : registry.scanned) {
+        known_paths.emplace(id, record->path);
+    }
+    mutex_unlock(&registry.mutex);
+
+    // Stat each manifest and parse it entirely without registry.mutex held (due to filesystem IO being slow)
+    std::vector<std::unique_ptr<ScannedAppManifest>> new_records;
+    for (const auto& app_dir : found_app_dirs) {
+        auto manifest_path = app_dir + "/manifest.properties";
+        if (!app_fs_is_file(manifest_path)) {
+            continue;
+        }
+
+        AppMetadata metadata {};
+        if (app_metadata_parse(manifest_path.c_str(), &metadata) != ERROR_NONE) {
+            LOG_W(TAG, "Invalid manifest at %s", manifest_path.c_str());
+            continue;
+        }
+
+        if (known_paths.contains(metadata.app_id)) {
+            continue; // already registered by an earlier scan
+        }
+
+        auto record = std::make_unique<ScannedAppManifest>();
+        record->id = metadata.app_id;
+        record->name = metadata.app_name;
+        record->path = app_dir;
+        record->manifest = AppManifest {
+            .id = record->id.c_str(),
+            .name = record->name.c_str(),
+            .category = APP_CATEGORY_USER,
+            .location = { APP_LOCATION_PATH, const_cast<char*>(record->path.c_str()) },
+            .flags = 0,
+        };
+        new_records.push_back(std::move(record));
+    }
+
+    // Anything a previous scan registered whose directory has since disappeared  gets unregistered below.
+    std::vector<std::string> missing_ids;
+    for (const auto& [id, path] : known_paths) {
+        if (!app_fs_is_directory(path)) {
+            missing_ids.push_back(id);
+        }
+    }
+
+    // app_manager_add()/app_manager_remove() take app-module's own ledger mutex internally -
+    // calling them while holding registry.mutex would establish a registry.mutex -> ledger-
+    // mutex lock order that any future opposite-order path would deadlock against, so these
+    // also run with registry.mutex released. registry.mutex is taken only afterward, briefly,
+    // to publish the results (plain in-memory map updates, no I/O or other locks involved).
+    for (const auto& id : missing_ids) {
+        app_manager_remove(id.c_str());
+    }
+    std::vector<std::unique_ptr<ScannedAppManifest>> added_records;
+    for (auto& record : new_records) {
+        if (app_manager_add(&record->manifest) == ERROR_NONE) {
+            added_records.push_back(std::move(record));
+        } else {
+            LOG_E(TAG, "Failed to register app %s (duplicate id?)", record->id.c_str());
+        }
+    }
+
+    mutex_lock(&registry.mutex);
+    for (const auto& id : missing_ids) {
+        registry.scanned.erase(id);
+    }
+    for (auto& record : added_records) {
+        registry.scanned[record->id] = std::move(record);
+    }
+    mutex_unlock(&registry.mutex);
+}
+
+} // extern "C"

Modules/app-module/source/symbols.cpp

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/event.h>
+#include <app/install.h>
+#include <app/manager.h>
+#include <app/metadata.h>
+#include <app/paths.h>
+#include <app/scheduler.h>
+
+#include <service/manager.h>
+
+#include <tactility/error.h>
+#include <tactility/module.h>
+
+extern "C" {
+
+extern ServiceManifest app_internal_loader_service_manifest;
+
+const ModuleSymbol app_module_symbols[] = {
+    // app/event
+    DEFINE_MODULE_SYMBOL(app_event_subscribe),
+    DEFINE_MODULE_SYMBOL(app_event_unsubscribe),
+    DEFINE_MODULE_SYMBOL(app_event_emit),
+    DEFINE_MODULE_SYMBOL(app_event_await),
+    // app/install
+    DEFINE_MODULE_SYMBOL(app_get_install_path),
+    DEFINE_MODULE_SYMBOL(app_install),
+    DEFINE_MODULE_SYMBOL(app_uninstall),
+    // app/manager
+    DEFINE_MODULE_SYMBOL(app_manager_start),
+    DEFINE_MODULE_SYMBOL(app_manager_start_with_parameters),
+    DEFINE_MODULE_SYMBOL(app_manager_start_for_result),
+    DEFINE_MODULE_SYMBOL(app_manager_stop),
+    DEFINE_MODULE_SYMBOL(app_manager_finish),
+    DEFINE_MODULE_SYMBOL(app_manager_get_state),
+    DEFINE_MODULE_SYMBOL(app_manager_find_manifest),
+    DEFINE_MODULE_SYMBOL(app_manager_for_each_manifest),
+    DEFINE_MODULE_SYMBOL(app_manager_add),
+    DEFINE_MODULE_SYMBOL(app_manager_remove),
+    DEFINE_MODULE_SYMBOL(app_manager_get_topmost_instance_id),
+    DEFINE_MODULE_SYMBOL(app_manager_get_topmost_app_id),
+    DEFINE_MODULE_SYMBOL(app_manager_install_path_add),
+    DEFINE_MODULE_SYMBOL(app_manager_install_path_scan),
+    // app/metadata
+    DEFINE_MODULE_SYMBOL(app_metadata_parse),
+    // app/paths
+    DEFINE_MODULE_SYMBOL(app_paths_get_user_data_directory),
+    DEFINE_MODULE_SYMBOL(app_paths_get_user_data_path),
+    DEFINE_MODULE_SYMBOL(app_paths_get_assets_directory),
+    DEFINE_MODULE_SYMBOL(app_paths_get_assets_path),
+    // app/scheduler
+    DEFINE_MODULE_SYMBOL(app_scheduler_current_app_id),
+    // terminator
+    MODULE_SYMBOL_TERMINATOR
+};
+
+static error_t start() {
+    return service_manager_add(&app_internal_loader_service_manifest, /*auto_start=*/true);
+}
+
+static error_t stop() {
+    return service_manager_remove(app_internal_loader_service_manifest.id);
+}
+
+Module app_module = {
+    .name = "app",
+    .start = start,
+    .stop = stop,
+    .drivers = nullptr,
+    .symbols = app_module_symbols,
+    .internal = nullptr
+};
+
+}