Skip to content

Readme.md

Latest commit

 

History

History
545 lines (446 loc) · 15.5 KB

Readme.md

File metadata and controls

545 lines (446 loc) · 15.5 KB

FROG logo

FROG Language

Normative semantic layer for validated FROG programs
FROG — Free Open Graphical Language

Contents

1. Overview

Language/ defines what a validated FROG program means.

This directory is the normative semantic layer of the FROG repository.

It is not the source-format layer.
It is not the structural-validation layer.
It is not the execution-IR layer.
It is not the lowering layer.
It is not the backend-contract layer.
It is not the runtime layer.
It is not the IDE layer.

The ownership rule is: 

Expression/  -> what is written and structurally valid as canonical source
Language/    -> what the validated program means
IR/          -> what canonical execution-facing representation is derived from that meaning

The role of Language/ is to define the semantic truth that exists after structural validation and semantic admission, and before any canonical execution-facing representation is derived.

2. Architectural Position

The FROG repository separates architectural concerns on purpose.

The broad chain is: 

canonical .frog source
        |
        v
loadability
        |
        v
structural validation
        |
        v
validated program meaning
        |
        v
canonical Execution IR Document
        |
        v
lowering
        |
        v
backend contract / backend-oriented handoff
        |
        v
known compiler/runtime backend
        |
        v
deployable artifact

Language/ owns the semantic stage in that chain: 

validated program meaning

This means:

  • it is upstream of IR derivation,
  • it is downstream of canonical source and structural validation,
  • it is the first execution-relevant normative truth layer.

This also means that Language/ must not blur the boundary between:

  • source-owned structural validity,
  • semantic acceptance,
  • canonical execution-facing derivation,
  • implementation-side realization.

3. Ownership Boundary

Language/ owns semantic truth for validated programs.

It defines:

  • what a validated program means,
  • what source-visible control structures mean,
  • what explicit state and valid cycles mean,
  • what the execution model guarantees at language level,
  • what execution control and observation boundaries are safe and meaningful.

Language/ does not own:

  • canonical source serialization,
  • source-schema posture or machine-checkable source shape,
  • graphical source layout,
  • canonical Execution IR structure,
  • IR canonical JSON schema posture,
  • backend lowering policy,
  • backend contract shape,
  • runtime-private realization,
  • IDE authoring workflow,
  • primitive-local intrinsic behavior catalogs,
  • optional profile capability catalogs.

That separation matters because the language must remain stable and inspectable even when implementations, runtimes, validators, IR producers, and IDEs evolve independently.

4. Document Map

The surrounding repository architecture is: 

Expression/  -> source and structural validity
Language/    -> meaning
IR/          -> canonical execution-facing representation derived from meaning
Libraries/   -> intrinsic primitives
Profiles/    -> optional capabilities
IDE/         -> tooling

The internal structure of Language/ is currently: 

Language/
├── Readme.md
├── Expression to validated meaning.md
├── Control structures.md
├── State and cycles.md
├── Execution model.md
└── Execution control and observation boundaries.md

The semantic flow inside this layer is: 

structurally valid canonical source
          |
          v
Expression to validated meaning
          |
          v
Control structures + State and cycles
                  |
                  v
            Execution model
                  |
                  v
Execution control and observation boundaries
                  |
                  v
        canonical IR derivation

This is semantic layering, not a compiler pipeline. The documents in this directory define meaning and semantic boundaries that later layers depend on. They do not define one mandatory implementation pipeline.

Semantic validation before FIR.md makes the pre-FIR validation gate explicit. It should be read when the question is whether a structurally valid source file has enough accepted meaning for FIR derivation.

5. Current Documents

The documents currently published in this directory are:

  • Readme.md — architectural entry point for the semantic layer and its ownership boundary.
  • Expression to validated meaning.md — normative boundary from structurally valid canonical .frog source to validated program meaning.
  • Control structures.md — normative meaning of canonical control structures such as case, for_loop, and while_loop.
  • State and cycles.md — normative meaning of explicit local memory and valid feedback cycles.
  • Execution model.md — language-level execution-model core, including validated program meaning, activation, execution context, semantic milestones, and committed source-level state.
  • Execution control and observation boundaries.md — safe semantic observation points, pause-consistent snapshots, safe stop boundaries, and minimal completion / fault / abort boundaries.

Together, these documents define the current cross-cutting semantic baseline of the FROG language. They do not replace primitive-local behavior owned by Libraries/ or optional capability behavior owned by Profiles/.

6. Expression to Meaning Boundary

Expression/ and Language/ meet at one critical normative boundary: 

structurally valid canonical source
        |
        v
validated program meaning

That boundary is owned by Language/Expression to validated meaning.md.

Its role is to define:

  • what validation must establish before a program has language-level meaning,
  • which source-visible families directly contribute to validated execution meaning,
  • which source-visible families remain non-semantic or non-authoritative,
  • which distinctions must remain recoverable before IR derivation.

This document is downstream of source-owned structural validity and upstream of IR/Derivation rules.md.

It therefore prevents several architectural failures:

  • source representation being mistaken for semantic truth,
  • structural validation being mistaken for semantic acceptance,
  • validator behavior becoming hidden language law,
  • front-panel composition being mistaken for public interface semantics,
  • Execution IR becoming the first semantic authority.

7. Relation with Expression

Expression/ defines how a FROG program is serialized and represented in canonical source. It also defines what counts as structurally valid canonical source.

That includes source-visible families such as:

  • metadata,
  • interface,
  • diagram,
  • front panel,
  • connector,
  • icon,
  • IDE-facing recoverability and convenience material.

But source representation and structural validity are not yet validated language meaning.

The semantic reading rule is therefore: 

Expression/ defines the canonical source shape
Expression/ defines structural validity
Language/   defines what that structurally valid source means

The dedicated boundary document Expression to validated meaning.md makes that bridge explicit. It defines what successful semantic validation establishes as language-level meaning before any canonical execution-facing IR may be derived.

8. Relation with IR

IR/ is downstream of Language/.

The relation is: 

validated program meaning
        |
        v
canonical Execution IR Document

This means:

  • Language/ is not an IR document set,
  • IR/ must not redefine semantic truth,
  • IR derivation must preserve the distinctions established by validated program meaning.

More precisely:

  • Language/ defines the semantic truth of validated FROG programs,
  • IR/ defines the canonical execution-facing representation derived from that truth,
  • IR/ may make execution-facing consequences more explicit,
  • IR/ may not become the first owner of meaning,
  • IR/ may not collapse into one downstream compiler-family form.

The repository intentionally prevents this collapse: 

source               != semantics
structural validity  != semantic acceptance
semantics            != IR
IR                   != lowering
lowering             != backend contract
backend contract     != runtime-private representation

That separation is required for inspectability, portability, conformance, and independent implementation.

9. Relation with Libraries and Profiles

Language/ does not replace primitive-local intrinsic behavior defined in Libraries/.

It also does not replace optional standardized capability behavior defined in Profiles/.

The ownership rule is: 

Libraries/  -> intrinsic primitive behavior
Profiles/   -> optional standardized capability behavior
Language/   -> cross-cutting semantic meaning of validated programs

So:

  • primitive catalogs stay where they belong,
  • profile capability rules stay where they belong,
  • Language/ defines the semantic layer that composes with them.

A program does not gain validated meaning from source shape alone. It gains validated meaning from semantic interpretation over structurally valid source together with the relevant language, library, and profile rules.

10. Relation with Implementations

Implementations may load, structurally validate, semantically validate, derive, lower, compile, execute, observe, and debug FROG programs.

But implementations do not own language truth.

The authority flow remains: 

repository law
      |
      v
conforming implementation behavior

Not the reverse.

Therefore:

  • a structural validator does not become hidden semantic law,
  • a semantic validator does not become hidden repository ownership,
  • a runtime does not define the meaning of the language,
  • a reference implementation remains non-normative even when executable,
  • implementation convenience must not silently redefine semantics,
  • a downstream compiler-family path such as LLVM must not become the definition of FROG meaning.

11. Current Repository Posture

The current repository posture is intentionally staged.

At this stage:

  • canonical source structure and source-schema posture are already separated into Expression/,
  • structural validity is already treated explicitly as a source-owned stage,
  • semantic meaning is separated into Language/,
  • canonical execution-facing derived representation is separated into IR/,
  • the repository already supports public examples, conformance material, and a non-normative reference implementation path.

This means Language/ must stay disciplined:

  • it must not absorb source serialization concerns,
  • it must not absorb source-schema posture,
  • it must not absorb IR wire-shape concerns,
  • it must not absorb implementation-private policy,
  • it must make semantic truth explicit enough that later layers stay honest.

More specifically, the semantic layer must remain strong enough that:

  • the canonical Execution IR Document can be derived without becoming the first owner of meaning,
  • lowering can specialize without laundering semantics,
  • backend contracts can declare assumptions without redefining language truth,
  • downstream compiler families can consume FROG without replacing it.

The semantic layer should therefore remain compact, explicit, and durable.

12. Summary

Language/ defines what a validated FROG program means.

It sits:

  • after canonical source and structural validation,
  • before canonical execution-facing IR,
  • before lowering, backend contract, runtime realization, and IDE workflow concerns.

The essential reading rule remains: 

Expression/  -> source and structural validity
Language/    -> meaning
IR/          -> canonical execution-facing representation

That separation is required so that FROG can remain:

  • inspectable,
  • portable,
  • conformant,
  • independently implementable,
  • architecturally durable as an open graphical language.