Glossary and Checklists

Glossary and Checklists

Use this page when reviewing work or onboarding a developer to Forsetti.

Glossary

Term	Meaning
App module	A ForsettiAppModule that represents a complete single-application UI.
UI module	A ForsettiUIModule that contributes UI to the host.
Service module	A non-visual ForsettiModule for background behavior or shared provider roles.
Manifest	JSON contract that declares module identity, platform support, version range, capabilities, entitlement product, entry point, default role, and runtime requirements.
Manifest template version	Template contract version. Current authoring target is 1.1.
Entry point	String key used by ModuleRegistry to create a module instance.
Capability	Declared permission-like runtime need.
Runtime requirement	Manifest declaration for I/O, UI, and data isolation expectations.
Default module role	Manifest role such as ui, shared_database, authentication, diagnostics, api, or security.
Registration record	Persisted manifest identity and hash used to detect stale or mismatched module registration.
Entitlement	Unlock state for a module, usually tied to product ID or purchase state.
UI contribution	Structured toolbar, injection, overlay, or theme data from a UI/app module.
Slot	Host-defined placement target for injected views.
Overlay route	Route contract resolved by a host router.
Semantic version	MAJOR.MINOR.PATCH version value used by Forsetti release automation and runtime compatibility.

Module PR Checklist

flowchart TD
    Type["Module type"] --> Identity["Descriptor and manifest identity"]
    Identity --> Manifest["Schema 1.1 manifest"]
    Manifest --> Capabilities["Minimal capabilities"]
    Capabilities --> Runtime["Runtime requirements"]
    Runtime --> Registry["Entry point registered"]
    Registry --> Tests["Focused tests"]

Loading

• Module type is correct: service, ui, or app.
• Swift class conforms to the protocol required by moduleType.
• ModuleDescriptor, module manifest, bundled manifest JSON, and ModuleRegistry entry point match.
• Manifest file is bundled under Resources/ForsettiManifests.
• Current modules declare manifestTemplateVersion and runtimeRequirements.
• Requested capabilities are minimal and accurate.
• defaultModuleRole is present only when the module provides that role.
• iapProductID is present only when activation should be gated.
• start(context:) is fast and idempotent.
• stop(context:) releases module-owned resources.
• UI/app modules declare every contributed ID under runtimeRequirements.ui.
• UI modules register every injected viewID with the host.
• Tests cover discovery, registration, activation, entitlement, runtime requirement, and UI contribution behavior where relevant.

Host Integration Checklist

flowchart TD
    Package["Add package products"] --> Services["Register services"]
    Services --> Entitlements["Choose entitlement provider"]
    Entitlements --> Registry["Build module registry"]
    Registry --> Runtime["Create runtime"]
    Runtime --> Controller["Create host controller"]
    Controller --> Views["Register injected views"]
    Views --> Boot["Boot runtime"]
    Boot --> Verify["Run verification"]

Loading

• App target links only the Forsetti products it needs.
• Production builds hide developer controls unless using dashboard pattern.
• Services are app-owned and registered by protocol.
• Default-role provider modules are discovered before consumers that require them.
• Entitlement provider matches platform and build mode.
• Slot catalog and base destination catalog are stable.
• Errors are logged and surfaced appropriately for the deployment pattern.
• Theme masks are handled by host-owned styling unless the runtime path is intentionally extended.

Documentation Checklist

• README links to the relevant detailed docs.
• Wiki pages are updated when architecture, API, workflows, templates, or runtime behavior change.
• Mermaid diagrams are kept aligned with current code paths.
• Manifest examples use schema 1.1 and manifest template 1.1.
• Versioning guidance matches pr-version.yml and Scripts/update-pr-version.py.
• No stale claims remain about denied capabilities, manifest fields, or release behavior.

Release Checklist

• Pull request title follows the conventional format used by lint-pr.yml.
• Non-chore: PRs include the expected version-file update.
• swift test passes.
• Scripts/verify-forsetti-guardrails.sh passes.
• Framework version files are aligned: version.txt, Sources/ForsettiCore/ForsettiVersion.swift, and the README marker.
• .release-please-manifest.json changes only as retained release configuration state.
• Changelog describes behavior and documentation changes when releasing.
• Wiki pages are updated manually for architecture, API, or workflow changes.
• The tracked wiki archive is regenerated after wiki page changes.
• Release publication handles tags, changelog updates, and GitHub releases after changes reach main.

Red Flags

Red Flag	Why It Matters
App code imports framework internals.	Breaks the sealed framework contract.
Module reaches directly into host UI.	Bypasses structured UI composition.
Manifest and descriptor disagree.	Discovery and activation become hard to reason about.
Manifest template 1.1 omits runtime requirements.	Reviewers cannot validate service, UI, and data expectations.
Service implementation is created inside a reusable UI module.	Couples module to app infrastructure.
Debug entitlement provider in production.	Paid features may unlock incorrectly.
Long work inside start(context:).	Runtime boot and activation become slow or fragile.
PR title uses chore: for product behavior changes.	Version automation will intentionally skip the version update.