ADR 0004: API profile model
ADR 0004: API profile model
- Status: Accepted historically; active product scope narrowed by ADR 0011
- Date: 2026-11-04
Context
GFA BASIC language semantics and platform APIs must not be conflated. Amiga and Atari ST implementations share historical lineage, but their platform APIs and version-specific behavior require separate evidence. The output target is also independent: a Linux executable may implement a documented legacy platform API through a compatibility runtime without becoming a native executable for that platform.
Decision
- Treat the selected source dialect/version and the language core as distinct from platform API profiles.
- The initial platform API profile identifiers are `amiga` and `atari-st`.
- Do not define a separate `core` or `common` API profile in the initial model. Platform-independent language constructs belong to the selected dialect's language core.
- Select zero or more API profiles explicitly. Do not infer or enable a profile from the output target.
- Keep profile selection independent of the output target. The initial Linux target may implement selected Amiga or Atari ST API semantics through project-owned runtime interfaces.
- Store platform/version/OS-library applicability on profile and declaration metadata rather than encoding an assumed version range into the profile identifier.
- Conflicting declarations across enabled profiles must produce deterministic diagnostics. Never resolve conflicts silently by load order or implicit precedence.
- A registry entry is not an implementation or support claim. Supported declarations require source evidence, semantic contracts, runtime mappings, target status, and conformance tests.
- Automatic profile detection, if added, is advisory unless a user explicitly selects an inference mode.
The detailed policy is maintained in API-PROFILES.md. CLI/configuration syntax and registry serialization remain separate decisions.
Alternatives considered
- Treat language core as a `core` API profile: rejected because it conflates language semantics with selectable platform APIs.
- Add an implicit `common` API profile: rejected until a source-backed set of platform-independent API declarations is identified.
- Infer Amiga/Atari API profile from Linux/Amiga output target: rejected because source API semantics and output platform are independent.
- Resolve duplicate declarations by profile load order: rejected because it makes compilation order-dependent and hides ambiguity.
- Encode all version information in profile identifiers: rejected because OS/library versions and GFA interpreter/compiler versions may evolve independently.
Consequences
- The language core remains independent of platform API declarations.
- Amiga and Atari ST profiles can evolve independently and can be selected together only when conflicts are resolved explicitly.
- CLI and registry work must preserve explicit dialect/profile/target separation.
- The accepted model does not claim that any Amiga or Atari API declaration is complete, implemented, or conformant. ADR 0011 narrows the active product to the Amiga GFA BASIC 3.5 API profile only; Atari ST profile support is out of scope. The earlier multi-profile decision remains historical architecture context, not a current product commitment.
- Additional profiles require evidence, dependency/conflict rules, runtime capability status, and tests.