Skip to content

Readme.md

Latest commit

 

History

History
869 lines (669 loc) · 25.8 KB

Readme.md

File metadata and controls

869 lines (669 loc) · 25.8 KB

FROG logo

FROG Profiles

Optional standardized capability families for FROG
FROG — Free Open Graphical Language

Contents

1. Overview

This directory defines optional standardized capability families for FROG.

A profile is a standardized specification layer that extends the usable capability surface of FROG without redefining the canonical source structure of the language core, without replacing the cross-cutting execution semantics owned by the core language architecture, and without turning one implementation strategy into mandatory language law.

Profiles exist to standardize capability areas that matter for real ecosystems but that should not be treated as intrinsic, always-present, mandatory parts of the minimal FROG core.

Within the current repository architecture: 

Expression/
   - canonical source representation

Language/
   - normative validated-program meaning
   - cross-cutting execution semantics

Libraries/
   - intrinsic standardized primitive vocabularies

IR/
   - canonical execution-facing representation
   - derivation
   - construction
   - schema posture
   - lowering
   - backend contract

Profiles/
   - optional standardized capability families

IDE/
   - authoring
   - observability
   - debugging
   - inspection
   - related tooling responsibilities

Implementations/
   - non-normative executable realization workspaces

A profile therefore extends the standardized capability surface of FROG, but it does so from outside the intrinsic core.

2. Purpose of Profiles

The purpose of this directory is to provide a clean architectural home for specification material that is:

  • standardized,
  • useful across multiple implementations,
  • optional rather than mandatory for the minimal language core,
  • sometimes dependent on broader execution assumptions, deployment assumptions, host environments, interoperability contracts, capability classes, or target-facing restrictions.

This separation keeps the FROG core small, stable, portable, and durable while still allowing the standard to define broader capability surfaces where justified.

A profile is therefore neither:

  • a replacement for the language core,
  • a second hidden core-language layer,
  • a dumping ground for implementation-specific features,
  • a place where runtime-private realization becomes normative language truth,
  • nor an excuse to move core language meaning into optional documents.

3. Architectural Role

Profiles occupy a distinct architectural role between the minimal core standard and purely implementation-specific extensions.

They are intended to standardize capability families that are broader than one vendor-specific extension but narrower than the mandatory language core. 

FROG specification architecture
Expression/        - canonical source form
Language/          - normative validated-program meaning
Libraries/         - intrinsic standardized primitive vocabularies
IR/                - canonical derived execution representation and backend-facing boundaries
Profiles/          - optional standardized capability families
IDE/               - authoring and observability tooling
Implementations/   - non-normative executable realizations

This model preserves a stable architectural center while allowing the ecosystem to grow through bounded optional capability families.

Profiles are therefore part of the published FROG specification architecture, but they are not part of the minimal intrinsic core.

4. Scope of this Directory

This directory is the normative home of optional profile specifications.

A profile specification MAY define:

  • an optional primitive namespace or namespace family,
  • additional primitive catalogs and port models,
  • profile-local capability assumptions,
  • profile-local validation rules,
  • profile-local execution constraints that remain subordinate to the core language meaning,
  • target-facing capability classes,
  • deployment-facing capability classes,
  • runtime-facing capability contracts,
  • profile-specific terminology and behavior that remain outside the minimal intrinsic language surface,
  • optional capability claims that implementations MAY support explicitly,
  • profile-level execution contracts for bounded execution corridors, where justified,
  • portable capability catalogs needed by multiple tools without moving their ownership into the minimal core.

A profile specification MUST remain subordinate to the core repository architecture.

This means that a profile may add an optional capability layer, but it MUST do so without collapsing the ownership boundaries of Expression/, Language/, Libraries/, IR/, or IDE/.

5. Capability Taxonomy

To keep the architecture explicit, FROG distinguishes several different concepts that are related but must not be conflated.

5.1 Optional capability profiles

An optional capability profile is the top-level object standardized in this directory. It defines one bounded optional capability family that implementations may claim explicitly.

A profile is not automatically:

  • a target profile,
  • a deployment mode,
  • a backend family,
  • a runtime module.

A profile MAY define one or more of those related capability classes or constraints when that is part of its bounded scope.

5.2 Target-facing capability classes

A profile may define target-facing capability classes when a bounded optional corridor depends on explicit execution assumptions.

A target-facing capability class is not a private runtime module and not a backend implementation by itself. It is a standardized capability class that helps delimit where a profile applies.

Examples of target-facing posture that may be relevant inside published profiles include:

  • host-oriented native CPU execution,
  • UI-capable host environments,
  • restricted interoperability-ready environments.

These target-facing classes are profile-side constraints. They do not replace the core semantic model and they do not, by themselves, define runtime-private realization.

5.3 Deployment-facing capability classes

A profile may define deployment-facing capability classes when a bounded corridor depends on packaging, observability, or execution-environment assumptions.

A deployment-facing class may constrain how a prepared program is delivered or started. It is not the same thing as:

  • language semantics,
  • core IR structure,
  • backend family identity.

Examples of deployment-facing classes may include full-runtime-hosted execution, generated-launcher execution, self-contained executable packaging, statically linked native packaging, dynamically linked native packaging, or embedded-host packaging. These classes describe delivery and start posture. They do not, by themselves, decide what the source means or require every deployed program to carry a complete general-purpose runtime.

5.4 Backend families

A backend family is a class of downstream execution consumers or compiler consumers. Backend families remain downstream from the canonical FROG Execution IR.

Examples of backend-family posture that are already relevant in the current published repository include:

  • LLVM-oriented native CPU backend families,
  • other future native, VM, interpreter, or accelerator-oriented families that may later be bounded explicitly.

A backend family is not a profile by itself, although a profile MAY define bounded compatibility with one or more backend families.

5.5 Runtime-facing capability contracts

A runtime-facing capability contract is a standardized statement about assumptions, services, or guarantees expected at a runtime boundary.

It is not identical to:

  • canonical open IR,
  • backend contract ownership in IR/,
  • private runtime realization.

A profile MAY define runtime-facing capability expectations where justified, but those expectations MUST remain subordinate to the repository-wide separation between open IR, lowering, backend handoff, and private realization.

5.6 Profile-level execution contracts

A profile-level execution contract is a bounded profile companion document that closes the additional question: 

Given a lowered and backend-contract-emitted program
inside one accepted profile subset,
under what explicit assumptions
may execution actually begin?

A profile-level execution contract is therefore not:

  • the generic backend contract owned by IR/,
  • a universal runtime specification for all FROG programs,
  • a license to move private runtime realization into normative language truth.

Instead, it is a profile-side closure surface for one bounded execution corridor.

Compactly: 

backend contract
   =
standardized downstream handoff

profile-level execution contract
   =
additional bounded execution-start closure
for one published optional capability corridor

6. Profile vs Runtime Boundary

A profile may constrain or classify runtime-facing expectations, but it does not own one runtime implementation and does not replace the architectural runtime boundary.

This distinction matters especially for advanced capability surfaces. 

profile
   may define
capability assumptions

profile
   does not define
one private runtime realization

Likewise: 

profile
   may define
target-facing or deployment-facing classes

profile
   does not redefine
canonical open IR
or
backend contract ownership

Profiles therefore remain optional specification layers, not hidden runtime specifications.

Where a profile publishes an execution contract, that execution contract remains:

  • bounded,
  • subordinate to the rest of the repository architecture,
  • distinct from private runtime realization.

7. What Profiles MAY Define

A profile MAY define any bounded optional capability family that remains architecturally subordinate to the rest of the repository.

Examples already visible or directly supported by the current repository posture include:

  • interoperability surfaces,
  • restricted native compilation corridors,
  • bounded execution-side companion contracts,
  • portable widget-class catalogs and class-contract families,
  • tool-consumable capability metadata needed by multiple conforming implementations.

A profile MAY therefore state:

  • what optional capability claim exists,
  • what assumptions that claim requires,
  • what subset or bounded capability class it applies to,
  • what explicit rejection conditions apply when those assumptions are not met,
  • what additional execution-start assumptions must be satisfied when compilability alone is not enough.

8. What Profiles MUST NOT Define

A profile MUST NOT:

  • redefine canonical source structure,
  • redefine core validated-program meaning,
  • move intrinsic language truth out of the core architecture,
  • replace the ownership of Libraries/ for intrinsic primitives,
  • replace the ownership of IR/ for canonical execution representation, derivation, lowering, or backend contract,
  • replace the ownership of Expression/ for canonical widget-instance declaration or other source-owned forms,
  • replace the ownership of IDE/ for authoring ergonomics, Program Model realization, or editor-private workflow behavior,
  • turn one implementation strategy into mandatory language law,
  • present one private runtime design as though it were the only conforming meaning of the capability family,
  • collapse backend family, target-facing class, deployment-facing class, execution contract, runtime realization, and tool-private metadata into one ambiguous concept.

Profiles are optional architectural extensions. They are not ownership shortcuts.

9. Relation with Other Specification Layers

Profiles must remain readable relative to the rest of the repository.

The intended reading model is: 

Expression/
   defines canonical source structure

Language/
   defines validated meaning

Libraries/
   define intrinsic primitives

IR/
   defines canonical execution-facing representation,
   derivation,
   construction,
   schema posture,
   lowering,
   backend contract

Profiles/
   define optional standardized capability families
   that remain subordinate to all of the above

IDE/
   defines authoring and observability concerns

Implementations/
   provide non-normative executable workspaces

A profile may depend on these layers. It must not absorb them.

Where a profile publishes an execution contract, the intended reading remains: 

IR/
   keeps ownership of
backend handoff

Profiles/
   may add
bounded execution-side closure
for one optional capability corridor

The same boundary rule applies to richer UI capability families: 

Expression/
   keeps ownership of
widget-instance source representation

Libraries/
   keep ownership of
intrinsic frog.ui primitive identities

Profiles/
   may define
portable widget-class catalogs,
class contracts,
and optional rich UI capability families

IDE/
   may consume those contracts
for authoring and guided node generation
without becoming their normative owner

10. Profile Identification and Claims

Profiles are intended to be claimable.

An implementation MAY state that it supports:

  • the core language only,
  • the core language plus one or more published profiles,
  • different subsets or maturity levels of profile support, provided those claims are explicit and not misleading.

A program, toolchain, or deployment path MAY also declare that it targets a given profile when that is meaningful and explicitly defined by the relevant profile specification.

A profile claim MUST remain precise. For example:

  • interop means support for the published interoperability profile, not generic foreign-function support of unknown scope,
  • native_cpu_llvm means support for the published optional native CPU LLVM-oriented compilation profile, not a claim that LLVM defines FROG or that every valid FROG program is automatically compatible with that corridor,
  • ui_widget_classes means support for the published optional widget-class contract profile, not a vague claim that one IDE happens to expose proprietary property panels or object reflection.

If a profile also publishes an execution contract, support claims SHOULD remain equally precise. For example:

  • support for the compilation profile alone,
  • support for the compilation profile plus its published execution contract,
  • support for only a bounded execution-ready subset of that pair.

Vague claims such as “supports all advanced features” are not profile claims. Explicit profile naming is preferred.

11. Current Profile Specifications

The currently published profile specifications in this directory are:

  • Interop.md — optional interoperability capability profile,
  • Native CPU LLVM.md — optional native CPU compilation profile for LLVM-oriented backend families,
  • Native CPU LLVM Execution contract.md — optional Native CPU LLVM companion execution contract for bounded execution-start closure,
  • UI Widget Classes.md — optional rich UI widget-class catalog and class-contract profile for portable property, method, part, and event surfaces.

Profiles MAY also be accompanied by narrower companion documents when their corridor requires additional bounded closure, including profile-level execution contracts.

11.1 Interop

Interop.md is the normative home for the optional interoperability capability surface, including the standardized home for capability families that should not remain in the intrinsic core library layer.

11.2 Native CPU LLVM

Native CPU LLVM.md defines a first optional compilation-oriented profile for a conservative bounded subset capable of traveling through: 

validated meaning
   ->
canonical FROG Execution IR
   ->
lowering
   ->
backend contract
   ->
LLVM-oriented native CPU backend family

This profile exists to close one serious industrial compilation corridor without collapsing the language into LLVM and without redefining IR ownership inside Profiles/.

It should be read as:

  • a bounded optional capability claim,
  • a target-facing native compilation profile,
  • a backend-family-oriented downstream compatibility claim,
  • not a replacement for the core language or core IR stack.

11.3 Native CPU LLVM Execution Contract

Native CPU LLVM Execution contract.md is the companion execution-side closure document for the same bounded Native CPU LLVM profile family.

Its role is distinct:

  • Native CPU LLVM.md closes the compilation corridor,
  • Native CPU LLVM Execution contract.md closes the additional execution-start assumptions for a bounded accepted subset,
  • IR/Backend contract.md remains the generic consumer-facing backend handoff owned by IR/.

The intended distinction is: 

compilation profile
   =
bounded route to backend-family consumability

backend contract
   =
generic standardized downstream handoff

profile-level execution contract
   =
additional bounded execution-start closure
for one accepted optional corridor

11.4 UI Widget Classes

UI Widget Classes.md is the optional rich UI widget-class profile.

Its role is to standardize a portable widget-class catalog and class-contract surface for richer front-panel object ecosystems without moving ownership away from:

  • Expression/ for canonical widget-instance source declaration,
  • Libraries/UI.md for intrinsic frog.ui.* executable primitives,
  • IDE/ for Program Model realization and editor behavior,
  • IR/ for execution-facing preservation, lowering, and backend handoff.

This profile should be read as:

  • a bounded optional capability claim for portable widget-class catalogs,
  • a class-contract surface for property, method, part, and event declaration,
  • a validation aid for object-style UI interaction,
  • not a universal rendering toolkit specification,
  • not a hidden runtime-private widget ABI,
  • not a replacement for core widget-instance source ownership.

12. Core Conformance, Profile Support, and Certification

Core language conformance and profile support are related but distinct.

An implementation may:

  • conform to the FROG core without supporting any optional profile,
  • conform to the FROG core and also support one or more optional profiles,
  • support only bounded subsets of a profile, provided those claims are explicit.

Accordingly: 

core conformance
   !=
profile support claim

profile support claim
   !=
support for every optional profile

support for one profile
   !=
support for every bounded subset,
every companion contract,
or every host environment

Where conformance material exists for a profile corridor, acceptance or rejection under that corridor SHOULD remain explicit and separately claimable.

The same discipline applies to rich UI profiles:

  • support for widget-instance source is not automatically support for a rich widget-class catalog,
  • support for property-read nodes is not automatically support for every class family,
  • support for one class family is not automatically support for every declared event surface or runtime host capability.

13. Profile Evolution

Profiles allow the published specification architecture to grow without destabilizing the minimal core.

Over time, new profiles may standardize additional bounded capability families. That growth should remain disciplined and should follow already justified repository-visible closure fronts rather than speculative category expansion.

New profiles SHOULD:

  • name one bounded capability family clearly,
  • state their assumptions explicitly,
  • preserve ownership boundaries across the repository,
  • avoid turning one implementation strategy into universal truth,
  • remain claimable, inspectable, and compatible with conformance growth where relevant.

The preferred growth posture is therefore: 

stabilize one high-value published corridor
   ->
align profile claim, conformance, and reference consumption
   ->
only then open the next optional family

14. Status

This directory is normative.

It defines the architectural role of optional standardized capability families within the published FROG specification.

At the current repository posture, this surface should be read as:

  • published and meaningful,
  • already containing high-value bounded corridors,
  • still under active closure for some of its most important families.

That evolution must remain architecture-preserving:

  • the core language remains the core language,
  • core IR ownership remains in IR/,
  • intrinsic primitive ownership remains in Libraries/,
  • source ownership remains in Expression/,
  • authoring and observability ownership remain in IDE/,
  • profiles remain optional standardized capability families.

15. Summary

FROG profiles are optional standardized capability families that extend the usable capability surface of the language without redefining the minimal core.

They exist so that the repository can standardize broader industrially meaningful capability corridors while preserving architectural ownership boundaries.

In short: 

Expression/
   owns canonical source

Language/
   owns validated meaning

Libraries/
   own intrinsic primitive vocabularies

IR/
   owns canonical execution-facing representation,
   lowering,
   and backend handoff

Profiles/
   own bounded optional capability families

IDE/
   owns authoring and observability tooling

Implementations/
   remain non-normative executable workspaces

This makes it possible for FROG to grow through explicit optional profiles such as interoperability, bounded native compilation corridors, bounded execution-side closures, and portable rich UI widget-class capability families, without collapsing the architecture into one implementation or one runtime.