Skip to content

FROG-Repository-Guide.md

Latest commit

 

History

History
402 lines (340 loc) · 16.4 KB

FROG-Repository-Guide.md

File metadata and controls

402 lines (340 loc) · 16.4 KB

FROG Repository Guide

Public repository orientation: what this repository defines, what it deliberately does not define, how the public specification boundary works, and where readers should go next.

This document preserves long-form material that was previously maintained in the public root README. The root README now acts as a concise orientation page and links here for detail.

What this repository defines

This repository defines the published FROG specification. It is the repository where the language and its surrounding specification layers are written, clarified, stabilized, and progressively closed.

Its role is to provide a durable open foundation for future:

  • IDEs,
  • validators,
  • runtimes,
  • compilers,
  • execution backends,
  • profile-supporting toolchains,
  • ecosystem services and integrations.

The repository also contains repository-level support material that helps make the specification inspectable in practice: named examples, conformance material, a non-normative reference implementation workspace, a strategic framing layer, a non-normative roadmap layer, and a centralized specification-versioning surface. Those areas support the published specification, but they do not replace its ownership boundaries.

This repository does not define one mandatory product implementation. It does not equate the language with one IDE, one runtime, one compiler, one vendor stack, or one deployment model.

Public Specification and Implementation Boundary

This repository defines the public FROG specification, including the canonical source model, FIR, public contracts, conformance material, examples, widget-facing material, and bounded non-normative reference implementation material.

The public reference runtime exists to keep the published specification executable, inspectable, and testable. It is intentionally bounded, non-production, and conformance-oriented. The current public reference runtime closure is Examples 01 through 15.

Graiphic may develop proprietary production implementations of FROG, including FROG Studio, production runtimes, deployment systems, enterprise integrations, certification tooling, and commercial support services. Those implementations are products built on top of the public specification. They do not redefine the FROG language specification and they do not make the public reference runtime mandatory. Runtime development for examples beyond Example 15 continues in Graiphic's proprietary Graiphic/FROG-Runtime repository unless a later public reference surface is explicitly promoted.

What FROG is not

  • FROG is not an IDE.
  • FROG is not a single runtime.
  • FROG is not a single compiler.
  • FROG is not a vendor product.
  • FROG is not a security guarantee just because a program is graphical.
  • FROG is an open language specification with distinct source, semantic, FIR, library, profile, IDE-facing, conformance, and version-governance layers.

That distinction matters. Multiple independent implementations should be possible around the standard. At the same time, the official FROG product identity and official branding can remain steward-controlled. Graiphic may build the flagship official IDE carrying the FROG name, while the language itself remains open and implementable by others.

Repository structure

This repository is organized by architectural responsibility plus repository-level support areas. The six core specification families remain the architectural baseline of FROG. The support areas exist to make that baseline more inspectable, testable, executable, and governable without moving normative ownership away from the specification layers. 

FROG/
│
├── Conformance/                      Public accept / reject / preserve expectations
├── Examples/                         Illustrative named source slices and executable example dossiers
├── Expression/                       Canonical source specification for .frog programs
├── IDE/                              IDE architecture, authoring, observability, debugging, and inspection
├── IR/                               Canonical open execution-facing representation and downstream handoff boundaries
├── Implementations/
│   └── Reference/                    Non-normative reference implementation workspace and executable prototypes
├── Language/                         Normative execution semantics for validated program meaning
├── Libraries/                        Intrinsic standardized primitive-library specifications
├── Profiles/                         Optional standardized capability-family specifications
├── Roadmap/                          Non-normative closure sequencing and milestone tracking
├── Strategy/                         Non-normative strategic framing layer
├── Versioning/                       Centralized specification-version governance and current-status matrix
│
├── assets/                           Shared repository assets used by README and GitHub Pages
├── CLA.md                            Contributor license agreement requirements
├── CONTRIBUTING.md                   Contribution process and contribution rules
├── GOVERNANCE.md                     Governance, stewardship, and ecosystem model
├── FROG logo.svg                     Official logo asset
├── LICENSE                           Repository license
├── Readme.md                         Repository landing page and architectural overview
└── frog-orville-chart.png            Positioning illustration used by the repository

The six core specification families are:

  • Expression/
  • Language/
  • IR/
  • Libraries/
  • Profiles/
  • IDE/

The current repository-level support and governance areas are:

  • Examples/ — illustrative named source cases and executable closure dossiers,
  • Conformance/ — expected outcomes for validation, preservation, and rejection,
  • Implementations/Reference/ — non-normative prototype workspace used to exercise the current reference path,
  • Versioning/ — centralized current corpus-governance and per-surface current-status reporting.

Runtime and native execution direction

The repository direction is intentionally explicit: published examples should become consumable through runtime-family and compiler-family paths without making either path the definition of FROG.

The current executable reference reading is: 

canonical .frog source
      |
      v
FIR
      |
      v
lowering
      |
      +----------------------------+----------------------------+
      |                            |
      v                            v
backend contract              LLVM-oriented module
      |                            |
      v                            v
runtime acceptance            native proof

For Examples 01 through 04, the runtime acceptance and LLVM proofs are intentionally narrow reference proofs. For Example 05, the repository carries the richer applicative path involving a front-panel package, widget values, widget references, UI property writes, explicit state, bounded iteration, runtime-family acceptance, and LLVM native proof material. Examples 06 through 15 currently exercise the public widget-front-panel runtime discipline for Boolean, String, Enum, Path, and Button across the C++, Python, and Rust reference runtimes. Examples 16 through 24 remain public post-boundary widget-facing material for Picture, Label, Decoration, Subpanel, Tab, Ring, Listbox, Table, and Tree while their runtime implementation line continues privately in Graiphic/FROG-Runtime. Runtime development for examples beyond Example 15 belongs to Graiphic's proprietary runtime work unless explicitly promoted later as public reference material.

The current repository-visible execution checks are:

  • ArtifactChecks/ — verifies that the executable corridor artifacts are present and coherent at a high level,
  • Deriver/ — checks .frog -> FIR for the published source-pattern families, including the current widget examples where supported,
  • Lowerer/ — checks FIR -> lowering for the published FIR-unit families, including the current widget examples where supported,
  • ContractEmitter/ — checks lowering -> backend contract,
  • Runtime/ — checks contract -> runtime acceptance snapshot,
  • LLVM/ — checks lowering -> LLVM module and, where requested, native build proof.

The reference implementation workspace remains stage-separated: Deriver, Lowerer, ContractEmitter, Runtime, and LLVM are downstream consumers of the published source/FIR/lowering corridor rather than semantic owners of the language.

Internal documentation map

The repository contains multiple normative and architectural documents. The map below summarizes the intended role of the major Markdown documents in the current baseline of the repository. 

FROG/
├── Readme.md
│   -> repository landing page and global architectural entry point
├── CONTRIBUTING.md
│   -> contribution workflow, expectations, and cross-document coherence rules
├── CLA.md
│   -> contributor license agreement entry point and legal contribution notice
├── GOVERNANCE.md
│   -> repository governance, stewardship model, conformance direction,
│      certification direction, and branding boundary
│
├── Examples/
│   └── Readme.md
│       -> numbered executable example progression and closure state
│
├── Conformance/
│   └── Readme.md
│       -> public conformance posture, staged expected outcomes,
│          preservation obligations, and rejection expectations
│
├── Implementations/
│   └── Reference/
│       ├── Readme.md
│       │   -> non-normative reference workspace overview
│       ├── checks.md
│       │   -> repository-visible check commands
│       ├── ArtifactChecks/
│       │   -> preflight checks for published reference artifacts
│       ├── Deriver/
│       │   -> supported .frog -> FIR reference derivation
│       ├── Lowerer/
│       │   -> supported FIR -> lowering reference lowering
│       ├── ContractEmitter/
│       │   -> lowering -> backend contract materialization
│       ├── Runtime/
│       │   -> backend contract -> runtime acceptance checks
│       ├── LLVM/
│       │   -> lowering -> LLVM-oriented native proof modules
│       └── Pipeline/
│           -> coordinated reference check pipeline
│
├── Expression/
│   -> canonical source representation
├── Language/
│   -> normative execution semantics
├── IR/
│   -> FIR, derivation rules, lowering, backend contract posture
├── Libraries/
│   -> intrinsic primitives, widget class law, and Default realizations
├── Profiles/
│   -> optional standardized capability-family specifications
├── IDE/
│   -> authoring, observability, debugging, and inspection
└── Versioning/
    -> centralized status and governance matrix

Recommended reading path

Readers who are new to the repository should normally approach it in the following order: 

Readme.md
   |
   v
Expression/Readme.md
   |
   v
Expression/Schema.md
   |
   v
Language/Readme.md
   |
   v
IR/Readme.md
   |
   v
Libraries/Readme.md
   |
   v
Profiles/Readme.md
   |
   v
IDE/Readme.md

Readers who want to understand the currently published executable reference path should then continue with: 

Examples/Readme.md
   |
   +-- Examples/01_pure_addition/Readme.md
   +-- Examples/02_ui_value_roundtrip/Readme.md
   +-- Examples/03_ui_property_write/Readme.md
   +-- Examples/04_stateful_feedback_delay/Readme.md
   \-- Examples/05_bounded_ui_accumulator/Readme.md
        |
        v
Implementations/Reference/Readme.md
   |
   v
Implementations/Reference/checks.md
   |
   v
Implementations/Reference/check_reference_workspace.py

That second path answers a staged set of questions:

  • Examples/ — which executable slices are being used,
  • Examples/01_* through Examples/04_* — which isolated concerns are covered before the full corridor,
  • Examples/05_bounded_ui_accumulator/ — which combined applicative corridor is currently the primary anchor,
  • Examples/06_* through Examples/15_* — which widget-front-panel runtime slices are currently covered,
  • Implementations/Reference/ — how the non-normative reference pipeline processes them,
  • Runtime/ — how backend contracts are checked through acceptance snapshots,
  • LLVM/ — how lowered units are checked through native proof modules.

Governance, official branding, and ecosystem

FROG is governed as an open specification. The repository is intended to remain readable, implementable, and usable by independent parties while preserving long-term architectural coherence.

The current governance model is steward-led. Graiphic is the initial steward of the FROG specification repository and is responsible for maintaining architectural coherence, reviewing proposed changes, and publishing authoritative repository revisions.

Version governance, transition rules, and current repository status belong to the dedicated repository governance surfaces under Versioning/. Individual architectural documents should remain modular and should not become standalone version-governance documents.

The ecosystem direction is intentionally open: multiple independent IDEs, runtimes, compiler bridges, validators, and tooling layers may eventually coexist around the same open standard. At the same time, official branding and the official flagship product identity may remain controlled. Graiphic intends to build the flagship proprietary IDE on top of the FROG standard, and that official IDE may be the one carrying the formal FROG product name.

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

External contributions are governed through the repository contribution process and Contributor License Agreement requirements. See CONTRIBUTING.md and CLA.md.

Repository stewardship, governance direction, and ecosystem positioning are described in GOVERNANCE.md.

CLA Assistant

FROG — Free Open Graphical Language
Open graphical dataflow programming, specified as a language rather than owned as a product.