Coding Policy

Coding Policy

Forsetti Framework - Windows is governed by native-first, interface-first, dependency-controlled engineering rules. The machine-readable coding policy lives in implementation-policy.json; this page explains the rules in maintainer-facing language.

Rule Summary

Rule	Name	Practical Meaning
R001	Native Technologies Only	Production code uses C++20, Windows SDK/Microsoft tooling, CMake, MSVC, CppUnitTest, and approved vcpkg dependencies.
R002	Sealed Framework	Core/platform/host concrete framework types are not subclass extension points unless explicitly designed as interfaces.
R003	No Internal Patching	Consumers extend through public interfaces, templates, manifests, and module factories, not internal source edits.
R004	Public APIs Only	Modules interact with framework contracts through public headers.
R005	Strict OOP	Interface-first design, constructor dependency injection, and final concrete classes.
R006	One-Way Dependencies	Core has no platform/host/example/sample dependency; adapters, host, examples, and samples flow toward core.
R007	Run Verification	Pull requests must run the strongest available local guardrail verification.
R008	Proprietary Licensing	Source files carry the proprietary James Daley copyright header.
R009	Native Validation Closeout	Debug/Release CMake, CTest, PowerShell guardrails, MSVC, and vcpkg validation must be recorded on Windows before final native acceptance is marked passed.

Dependency Invariant

flowchart LR
    Core["ForsettiCore"]
    Platform["ForsettiPlatform"]
    Host["ForsettiHostTemplate"]
    Examples["Example modules"]
    Demo["ForsettiDemo"]

    Platform --> Core
    Host --> Platform
    Host --> Core
    Examples --> Core
    Demo --> Host
    Demo --> Examples

    Core -. no reverse import .-> Platform
    Core -. no host import .-> Host
    Platform -. no host import .-> Host
    Examples -. no adapter import .-> Platform
    Examples -. no host import .-> Host

Loading

Runtime Invariants

Invariant	Enforced By
Service modules may run concurrently.	ModuleManager service active set.
UI/app modules share one active surface slot.	ModuleManager::activateUIModule.
Activation requires compatibility, entitlement, registration, and runtime requirement checks.	ModuleManager::activateModuleLocked.
Factory-created modules must match the activation manifest.	validateResolvedModule.
Module service access is scoped by capability.	CapabilityScopedServiceProvider.
Module-to-module messages use framework-owned source identity.	ForsettiContext::sendMessage.
Reserved event namespaces are blocked.	DefaultModuleCommunicationGuard.
UI contributions require matching capabilities and declared UI IDs.	validateUIContributions.
Theme masks remain framework policy unless explicitly declared and approved.	sanitizedUIContributions.
Default module roles must be type-compatible and resolvable when required.	DefaultModuleCatalog and ModuleRequirementValidator.

Code Style

• Use C++20 and MSVC-compatible constructs.
• Keep public contracts in include.
• Keep implementation details in src.
• Prefer RAII and standard library ownership types.
• Avoid raw new/delete.
• Keep concrete classes final unless extension is intentional.
• Prefer constructor dependency injection.
• Keep comments useful and contract-oriented.

Validation Expectations

.\Scripts\verify-forsetti-guardrails.ps1

This wrapper is the local acceptance path for ordinary changes on Windows/MSVC. When it cannot run, record the missing toolchain blocker exactly and run available static, JSON, manifest, script, and repository surface checks.

Documentation Expectations

Docs are part of the framework surface. Update them when a change affects:

• Public module contracts.
• Manifest shape or validation rules.
• Runtime lifecycle semantics.
• Registration, default role, or runtime requirement behavior.
• Capability behavior.
• Platform adapter behavior.
• Host template composition behavior.
• Build/test workflow.
• Governance or owner decision status.