Module System

Module System

Forsetti modules are runtime units described by manifests and instantiated through registry factories. A module is never trusted solely because a factory returns an object. The returned object must match the activation manifest by ID, type, version, and bundled manifest content, and the manifest must have a confirmed registration record before activation.

Module Types

Type	Interface	Activation Model
service	IForsettiModule	Multiple service modules may run concurrently.
ui	IForsettiUIModule	Shares the single active UI/app surface slot.
app	IForsettiAppModule plus UI runtime contract	Shares the single active UI/app surface slot and represents an application-level module.

classDiagram
    class IForsettiModule {
      +descriptor() ModuleDescriptor
      +manifest() ModuleManifest
      +start(IForsettiModuleContext)
      +stop(IForsettiModuleContext)
    }
    class IForsettiUIModule {
      +uiContributions() UIContributions
    }
    class IForsettiAppModule {
      <<marker>>
    }
    IForsettiModule <|-- IForsettiUIModule
    IForsettiUIModule <|-- IForsettiAppModule

Loading

Manifest Fields

Current manifests use schema/template 1.1. Schema 1.0 remains loadable with safe default values for compatibility.

Field	Required	Type	Rule
schemaVersion	yes	string	Must be "1.0" or "1.1"; current manifests use "1.1".
manifestTemplateVersion	yes for 1.1	string	Current template version is "1.1".
moduleID	yes	string	Unique module identity; must not be blank or path-like.
displayName	yes	string	Human-readable display name.
moduleVersion	yes	SemVer object	Must match descriptor version.
moduleType	yes	string	service, ui, or app.
supportedPlatforms	yes	string array	Must include exact value "Windows".
minForsettiVersion	yes	SemVer object	Current framework version must be greater than or equal to it.
maxForsettiVersion	no	SemVer object or null	Current framework version must be less than or equal to it when present.
capabilitiesRequested	no	string array	Exact capability strings.
iapProductID	no	string or null	Optional entitlement product ID.
entryPoint	yes	string	Registry factory key; must not be blank or path-like.
defaultModuleRole	no	string or null	Optional default role such as ui or shared_database; role/type consistency is validated.
runtimeRequirements	yes for 1.1	object	Declares I/O requirements, UI IDs, and data isolation.

Example Service Manifest

{
  "schemaVersion": "1.1",
  "manifestTemplateVersion": "1.1",
  "moduleID": "com.forsetti.module.example-service",
  "displayName": "Example Service",
  "moduleVersion": { "major": 0, "minor": 1, "patch": 0, "prerelease": null },
  "moduleType": "service",
  "supportedPlatforms": ["Windows"],
  "minForsettiVersion": { "major": 0, "minor": 2, "patch": 0, "prerelease": null },
  "maxForsettiVersion": null,
  "capabilitiesRequested": ["storage", "telemetry", "event_publishing"],
  "iapProductID": null,
  "entryPoint": "ExampleServiceModule",
  "defaultModuleRole": null,
  "runtimeRequirements": {
    "io": [
      {
        "requirementID": "storage.example-state",
        "kind": "storage",
        "access": "read_write",
        "required": true,
        "description": "Private example service state."
      }
    ],
    "ui": null,
    "dataIsolation": {
      "mode": "private_to_module",
      "ownedStoreIDs": ["example-service-state"],
      "requiredDefaultRoles": []
    }
  }
}

Runtime Requirements

flowchart TB
    Requirements["runtimeRequirements"]
    IO["io\nrequired services and access"]
    UI["ui\ncontrol, layout, theme, view, slot, toolbar, route, pointer IDs"]
    Isolation["dataIsolation\nprivate or framework-mediated shared stores"]
    Validator["ModuleRequirementValidator"]
    Activation["ModuleManager activation"]

    Requirements --> IO
    Requirements --> UI
    Requirements --> Isolation
    IO --> Validator
    UI --> Validator
    Isolation --> Validator
    Validator --> Activation

Loading

I/O requirement kinds map to capabilities. Required requirements fail activation when the corresponding governed service or default role is unavailable.

Module-Requestable Capabilities

Manifest String	Runtime Enum	Governs
networking	Capability::Networking	INetworkingService resolution.
storage	Capability::Storage	IStorageService resolution.
secure_storage	Capability::SecureStorage	ISecureStorageService resolution.
file_export	Capability::FileExport	IFileExportService resolution.
crypto_utilities	Capability::CryptoUtilities	Cryptographic utility requirements.
telemetry	Capability::Telemetry	ITelemetryService resolution.
routing_overlay	Capability::RoutingOverlay	Overlay schema and toolbar overlay actions.
toolbar_items	Capability::ToolbarItems	Toolbar item contributions.
view_injection	Capability::ViewInjection	View injection contributions.
event_publishing	Capability::EventPublishing	Module-originated event publishing and toolbar publish-event actions.
shared_database	Capability::SharedDatabase	Framework-mediated shared database role requirements.
authentication	Capability::Authentication	Authentication role requirements.
diagnostics	Capability::Diagnostics	Diagnostics role requirements.
api	Capability::API	API role requirements.
security	Capability::Security	Security role requirements.

The runtime also recognizes ui_theme_mask as Capability::UIThemeMask. It is reserved for framework-owned presentation policy; module-provided theme masks are preserved only when declared and then handled by policy-controlled surface state.

Discovery, Registration, And Factory Resolution

flowchart LR
    Files["ForsettiManifests/*.json"]
    Loader["ManifestLoader"]
    Manifests["ModuleManifest list"]
    Registration["ModuleRegistrationService\nconfirm canonical manifest"]
    Registry["ModuleRegistry"]
    Factory["entryPoint factory"]
    Module["IForsettiModule instance"]
    Validate["validateResolvedModule"]

    Files --> Loader
    Loader --> Manifests
    Manifests --> Registration
    Manifests --> Registry
    Registry --> Factory
    Factory --> Module
    Module --> Validate

Loading

ManifestLoader scans recursively for JSON files under manifest directories. Files that do not look like manifests are skipped; invalid manifests and duplicate module IDs fail discovery.

ModuleRegistrationService records canonical manifest hashes and confirms that the activation manifest still matches its registration record.

ModuleRegistry maps entryPoint strings to factory functions. Factory results are validated against the manifest used for activation.

Factory Identity Validation

ModuleManager::validateResolvedModule() checks:

• descriptor.moduleID equals manifest.moduleID.
• descriptor.type equals manifest.moduleType.
• descriptor.version equals manifest.moduleVersion.
• module.manifest() equals the activation manifest.

Mismatch diagnostics include expected and actual values so test logs can identify the bad field.

Compatibility Checks

flowchart TD
    Manifest["ModuleManifest"]
    Schema{"schema supported?"}
    Template{"template supported?"}
    Platform{"supports Windows?"}
    Min{"min version <= framework?"}
    Max{"max absent or >= framework?"}
    Policy{"capability policy allows requests?"}
    Compatible["compatible"]
    Rejected["compatibility error"]

    Manifest --> Schema
    Schema -- no --> Rejected
    Schema -- yes --> Template
    Template -- no --> Rejected
    Template -- yes --> Platform
    Platform -- no --> Rejected
    Platform -- yes --> Min
    Min -- no --> Rejected
    Min -- yes --> Max
    Max -- no --> Rejected
    Max -- yes --> Policy
    Policy -- no --> Rejected
    Policy -- yes --> Compatible

Loading

CompatibilityReport::isCompatible() returns true only when no issue has error severity.

Example Modules

Module	Target	Type	Capabilities	Notes
com.forsetti.module.example-service	ForsettiExampleServiceModule	service	storage, telemetry, event_publishing	Publishes framework start/stop events and owns private service state.
com.forsetti.module.example-ui	ForsettiExampleUIModule	ui	routing_overlay, toolbar_items, view_injection, ui_theme_mask, event_publishing	Contributes toolbar, view, overlay, and declared theme IDs.
com.forsetti.module.example-app	ForsettiExampleAppModule	app	toolbar_items, view_injection, event_publishing	Demonstrates app-level UI surface contribution.

Example modules demonstrate runtime integration. They are not privileged framework internals and do not depend on each other.