Skip to content

Readme.md

Latest commit

 

History

History
1061 lines (853 loc) · 31.1 KB

Readme.md

File metadata and controls

1061 lines (853 loc) · 31.1 KB

FROG logo

FROG Intermediate Representation Architecture

Architectural definition of the open execution-facing IR layer for FROG v0.1
FROG — Free Open Graphical Language

Contents

1. Overview

This directory defines the architectural home of open execution-facing representations in the FROG specification.

A FROG program is not authored directly as an execution IR. It is authored as canonical source, admitted through structural validity, interpreted as validated program meaning, and only then represented as a canonical open execution intermediate representation.

The purpose of IR/ is to ensure that execution-facing representation is not scattered across:

  • source-format documents,
  • source-schema artifacts,
  • IDE-internal authoring models,
  • cache payload examples,
  • primitive or profile catalogs,
  • runtime-private scheduler forms,
  • backend-specific realization documents,
  • host-private UI realization layers.

This directory therefore provides the durable normative home for:

  • the canonical Execution IR Document itself,
  • the derivation boundary from validated program meaning to canonical open IR,
  • the construction boundary for materially building conforming canonical IR documents,
  • the identity and mapping boundary that preserves attribution and recoverability,
  • the schema posture and machine-checkable validation surface of the canonical JSON IR form,
  • the first downstream-adjacent boundaries toward lowering and backend-facing handoff.
canonical source
      ->
structural validity
      ->
validated program meaning
      ->
canonical Execution IR Document
      ->
later specialization / lowering
      ->
backend-facing handoff
      ->
private realization

The core of this layer is the canonical open Execution IR bundle. The directory also contains downstream-adjacent documents that define how open IR connects to later stages without collapsing the open IR layer into runtime-private form.

Public Derivation and Private Implementation Boundary

The .frog -> FIR boundary is part of the public FROG specification. Independent implementations must be able to understand, validate, emit, and inspect canonical Execution IR without depending on Graiphic private runtimes, private IDE state, or private compiler internals.

The public repository may also publish bounded reference tools and proof artifacts for derivation, lowering, backend contracts, and LLVM-oriented native artifacts. Those tools are conformance-oriented reference material. They do not define Graiphic's production compiler, production lowering implementation, ABI strategy, scheduler, optimizer, deployment packager, runtime implementation, or IDE implementation.

The boundary is therefore: 

public specification:
  .frog source model
  validated program meaning
  canonical Execution IR / FIR
  derivation, construction, identity, schema, and conformance rules
  public lowering boundary invariants and backend handoff expectations

Graiphic private implementation:
  production source analysis implementation
  production lowering and LLVM/native artifact generation
  optimization strategy, ABI strategy, packaging closure, runtime, and IDE

2. Reading Legend

The diagrams in this README use the following visual legend:

  • Open specification-facing layer or document
  • Standardized boundary, correspondence, mapping, schema, or handoff
  • Lowering or target-specialization zone
  • Implementation-private realization zone
  • Semantic truth, attribution, recoverability, or diagnostic obligation

3. Why this Layer Exists

FROG deliberately separates several architectural levels that are often conflated in graphical systems:

  • the canonical saved source artifact,
  • the source-owned structural admission boundary,
  • the IDE editable in-memory model,
  • validated program meaning,
  • the canonical execution-facing representation used to prepare execution,
  • the later forms used to specialize execution for a target.

Without a dedicated IR layer, execution-facing representation tends to drift into:

  • editor-side convenience structures,
  • cache examples,
  • runtime-private scheduler graphs,
  • compiler-specific internal pipelines,
  • backend-private deployment formats,
  • UI-runtime-private object tables treated as if they were language truth.

The IR layer exists to stop that drift and to give execution-facing representation a stable architectural home. 

Expression/ says:
"what is saved and structurally admitted as source"

IDE/ says:
"what is edited"

Language/ says:
"what the validated program means"

IR/ says:
"what canonical open execution-facing representation is built
from that validated meaning"

Lowering says:
"how canonical open IR is specialized for a target"

Runtime says:
"how one implementation realizes execution internally"

4. Architectural Boundary

The shortest correct mental model of the surrounding architecture is: 

+-------------------+--------------------------------------------------+
| Layer             | Primary question answered                        |
+-------------------+--------------------------------------------------+
| Expression/       | What is the canonical saved source?              |
|                   | What counts as structurally valid source?        |
| Language/         | What does the validated program mean?            |
| Libraries/        | What intrinsic primitives exist?                 |
| Profiles/         | What optional standardized capabilities exist?   |
| IDE/              | How is the program authored and observed?        |
| IR/               | What canonical open execution-facing             |
|                   | representation is built from validated meaning?  |
+-------------------+--------------------------------------------------+

A second boundary view is: 

validated program meaning
          |
          v
canonical open Execution IR
          |
          v
identity / mapping / derivation / construction / schema boundary
          |
          v
lowering / backend preparation
          |
          v
compiler / backend / runtime-private realization

The key architectural rule is:

  • IR/ begins after validated program meaning,
  • IR/ defines the canonical open execution IR boundary artifact,
  • IR/ remains before lowering and backend-facing contract,
  • IR/ MUST remain distinct from runtime-private realization.

More precisely, the core open-IR bundle is:

  • Execution IR.md,
  • Derivation rules.md,
  • Construction rules.md,
  • Identity and Mapping.md,
  • Schema.md,
  • schema/.

The downstream IR-adjacent documents are:

  • Lowering.md,
  • Backend contract.md.

This architectural boundary also applies to UI and widget-related execution-facing structure:

  • IR may preserve execution-relevant widget identities, widget references, member addresses, and event categories where validated meaning requires them,
  • IR MUST NOT absorb host-side widget realization, SVG rendering strategy, or runtime-private UI object storage as if those were open IR truth.

5. Position in the Representation Pipeline

The intended position of the IR layer is illustrated below: 

Authoring side
--------------
IDE Program Model
        |
        v
canonical .frog source
        |
        v
Expression/

Admission side
--------------
loadability
        |
        v
structural validity
        |
        v
Expression/

Meaning side
------------
validated program meaning
        |
        +--> Language/
        +--> Libraries/
        +--> Profiles/

IR side
-------
Execution IR
Derivation rules
Construction rules
Identity and Mapping
Schema
        |
        v
IR/

Downstream IR-adjacent side
---------------------------
Lowering
Backend contract

Implementation side
-------------------
compiler preparation
backend mapping
runtime realization
deployment-specific forms

The transition into IR/ begins after the program has validated program meaning. An implementation MAY derive IR directly from canonical source, from a validated Program Model, or from another equivalent validated internal form, but the resulting IR MUST remain semantically grounded in validated program meaning rather than in parser-only acceptance, structural-source admission alone, or editor-only convenience state.

The practical corridor that the IR layer closes explicitly is: 

.frog source
    |
    v
loadability
    |
    v
structural validity
    |
    v
validated authoring form or equivalent
    |
    v
validated program meaning
    |
    v
derivation
    |
    v
identity / mapping preservation
    |
    v
construction
    |
    v
canonical Execution IR Document
    |
    v
canonical JSON validation
    |
    v
lowered / backend-facing forms
    |
    v
compiler / runtime-private forms

This is the practical corridor that the IR layer closes explicitly: 

validated program meaning
        ->
derivation
        ->
recoverable IR identity and mapping
        ->
material IR construction
        ->
canonical Execution IR Document
        ->
canonical JSON schema validation
        ->
later lowering and backend-facing handoff

6. Scope of this Directory

This directory owns the architectural answers to questions such as:

  • What open execution-facing representations are standardized by FROG?
  • What is the architectural boundary between validated program meaning and open IR?
  • Which execution-facing properties are preserved from validated program meaning into IR?
  • Which properties may be made more explicit in IR without changing semantic truth?
  • How is the canonical Execution IR Document derived and constructed from validated program meaning?
  • How are identity, attribution, and recoverability preserved between source-visible content and IR content?
  • How is the canonical JSON form of the Execution IR validated?
  • Where does open IR stop and later specialization begin?
  • What downstream handoff assumptions may be standardized without collapsing into runtime-private realization?
  • How widget-object interaction surfaces are preserved into open execution-facing form without absorbing host realization?

This directory therefore contains both:

  • core open-IR documents that define the open execution-facing layer itself, and
  • downstream IR-adjacent documents that define how later stages connect to that layer.
Core open-IR bundle
- Execution IR model
- derivation rules
- construction rules
- recoverable identity and mapping
- schema posture
- machine-checkable schema artifacts

Downstream IR-adjacent documents
- lowering
- backend contract

7. What this Directory Does Not Own

This directory does not define:

  • the canonical .frog source structure in full,
  • source-schema posture or machine-checkable source shape artifacts,
  • the public interface source model in full,
  • the front-panel source model in full,
  • the complete widget source model in full,
  • the complete .wfrog package-family definition in full,
  • the normative execution semantics of the language in full,
  • the intrinsic primitive catalogs in full,
  • the optional standardized profile catalogs in full,
  • the IDE Program Model,
  • IDE-facing debug UX or observability UX,
  • cache ownership,
  • runtime-private execution formats,
  • runtime-private widget object storage,
  • host-side widget realization packages,
  • SVG rendering strategy as such,
  • one mandatory compiler architecture,
  • one mandatory backend-family implementation,
  • one mandatory runtime-private storage model.

This non-ownership rule is essential. Without it, the IR layer would become a catch-all replacement for other parts of the architecture.

8. Relation with Surrounding Layers

8.1 Relation with Expression

Expression/ owns canonical source representation and structural validity. That ownership remains authoritative even when canonical IR exists.

  • canonical source identity MUST remain owned by Expression/,
  • the existence of an Execution IR document MUST NOT redefine what a valid .frog file is,
  • the absence of an embedded or sidecar IR artifact MUST NOT invalidate canonical source,
  • IR attribution SHOULD remain able to refer back to source-visible objects defined by Expression/.
.frog source
   is not
Execution IR

Execution IR
   is derived from
validated program meaning

structural validity
   is not
Execution IR

The same rule applies to related widget-oriented source packages:

  • .wfrog packages remain source-side package artifacts owned by the relevant Expression-side architecture,
  • IR may preserve the resolved consequences of validated widget package usage,
  • IR does not become the owner of widget package definition or realization-package architecture.

8.2 Relation with Language

Language/ defines what a validated FROG program means when it executes. That semantic layer remains authoritative even when one or more execution IR artifacts exist.

  • Language/ defines semantic truth,
  • IR/ defines canonical open execution-facing representation,
  • IR/ MUST NOT silently change language meaning,
  • IR/ MAY make semantic consequences more explicit where execution preparation requires it.
Language/ answers:
"What is true?"

IR/ answers:
"What open execution-facing representation is built
from that truth?"

For widget-object interaction, this means:

  • Language/ owns the validated meaning of widget-value participation and object-style widget interaction,
  • IR/ may encode execution-facing consequences of that validated meaning,
  • IR/ must not redefine widget law or host realization law.

8.3 Relation with Libraries and Profiles

Libraries/ owns intrinsic primitive vocabularies. Profiles/ owns optional standardized capability families. The IR layer does not re-own either catalog.

At the execution-facing level, uses of core primitives, lightweight standard library primitives, and optional profile-owned capabilities remain explicit. For example, a validated use of frog.image.decode_file_rgba8 should remain visible as a standard-library primitive reference in IR rather than being hidden as Picture-widget behavior or runtime-private image magic.

When that call later requires a provider, native dependency, host capability, or package artifact, FIR still owns the public call identity and typed participation. Lowering and backend contracts own the provider boundary, dependency closure, manifest-compatible handoff, and rejection conditions. Concrete provider binaries, loader behavior, ABI strategy, and runtime object storage remain implementation-owned.

  • primitive identity remains owned by the relevant library layer,
  • optional capability identity remains owned by the relevant profile layer,
  • IR/ derives execution-facing representation from validated use of those surfaces,
  • IR/ may standardize how those validated uses appear in open IR, but not what primitives or profiles exist in the first place.

This includes UI primitives such as:

  • frog.ui.property_read,
  • frog.ui.property_write,
  • frog.ui.method_invoke.

IR may standardize the execution-facing representation of validated uses of those primitives. IR does not own the primitive families themselves.

8.4 Relation with the IDE Program Model

The IDE Program Model is an authoring-facing internal or semi-internal representation used to support editing, round-trip operations, diagnostics workflows, and related tooling. It is not the same thing as the canonical open Execution IR.

  • the Program Model MAY contain editor-side convenience state,
  • the Program Model MAY preserve round-trip authoring detail that the canonical open IR does not own,
  • the canonical Execution IR SHOULD NOT depend on editor-only presentation state as if that state were part of validated program meaning.

This also applies to UI authoring state such as:

  • selection state,
  • zoom state,
  • designer-only handles,
  • panel editing overlays,
  • temporary widget inspection panels.

8.5 Relation with Cache Artifacts

A FROG source or toolchain MAY embed or associate cache artifacts that store derived execution-facing data such as frog.ir. However, the cache container does not own the architectural definition of IR. It only provides a storage or transport location for derived artifacts.

  • cache entries such as frog.ir MAY carry serialized canonical Execution IR data,
  • cache presence MUST NOT change canonical source meaning,
  • cache metadata MUST NOT affect execution semantics,
  • the normative meaning of Execution IR belongs in IR/, not in cache examples.
IR meaning
   lives in
IR/

serialized derived artifact
   may live in
cache entry: frog.ir

cache container
   is not
IR ownership

8.6 Relation with Observation, Debugging, and Diagnostics

This directory does not own debugger UX, probe presentation, watch presentation, or runtime command surfaces. It does own part of what makes later source-aligned observation and diagnostics possible:

  • recoverable identity and mapping,
  • attribution and correspondence carriers,
  • stable execution-facing categories,
  • a canonical open boundary that can be referred to before runtime-private realization begins.

In other words: 

IDE/
   owns
how users inspect and interact

IR/
   owns part of
what makes source-aligned inspection and attribution possible

9. Widget Object and UI Corridor

FROG v0.1 already distinguishes:

  • widget instance declaration in canonical source,
  • class-level widget law,
  • diagram-side widget interaction,
  • widget-oriented package definitions,
  • runtime interpretation,
  • host realization.

The IR layer must preserve that separation while still providing an execution-facing corridor for widget-relevant validated meaning.

9.1 What IR may preserve

IR may preserve execution-relevant widget-related information such as:

  • stable widget identities needed by execution-facing interaction,
  • distinction between natural widget value participation and object-style widget reference participation,
  • validated widget member addressing consequences,
  • event categories and event payload shapes where execution-facing form needs them,
  • attribution back to widget instances and addressed members.

9.2 What IR must not absorb

IR must not absorb:

  • widget class package ownership,
  • widget realization package ownership,
  • SVG asset ownership,
  • host-private widget composition strategies,
  • runtime-private UI object tables,
  • one implementation's rendering pipeline as if it were canonical open IR.

9.3 Practical corridor

The practical widget-related IR corridor is therefore: 

widget instance in canonical source
        ->
validated widget participation meaning
        ->
validated widget reference / member access meaning
        ->
execution-facing IR preservation of identities and accesses
        ->
later lowering / target adaptation
        ->
runtime and host realization

This corridor is especially important for:

  • widget_value,
  • widget_reference,
  • frog.ui.property_read,
  • frog.ui.property_write,
  • frog.ui.method_invoke.

Open IR may preserve their validated execution-facing structure. Open IR does not become the owner of widget realization itself.

10. Internal Document Structure

The current directory structure is: 

IR/
├── schema/
├── Backend contract.md
├── Construction rules.md
├── Derivation rules.md
├── Execution IR.md
├── Identity and Mapping.md
├── Lowering.md
├── Readme.md
└── Schema.md

This structure is intentionally split between:

  • the core open-IR bundle, and
  • the downstream IR-adjacent bundle.

The core open-IR bundle is:

  • Execution IR.md
  • Derivation rules.md
  • Source to FIR scope matrix.md
  • Library call model.md
  • Construction rules.md
  • Identity and Mapping.md
  • Schema.md
  • schema/

The downstream IR-adjacent bundle is:

  • Lowering.md
  • Backend contract.md

A coherent next closure direction for widget-object execution-facing structure would also make room for dedicated IR companion documents such as:

  • Widget object mapping.md,
  • UI interaction lowering.md,

Those documents are not required to understand the present directory posture, but they are a natural extension of the corridor defined here.

11. Document Ownership Split

The ownership split inside IR/ is: 

Execution IR.md
   - canonical open execution-facing architecture

Derivation rules.md
   - normative derivation from validated meaning to canonical IR

Source to FIR scope matrix.md
   - compact field-by-field guide for what .frog source facts become
     primary FIR, correspondence, downstream references, or exclusions

Library call model.md
   - public FIR posture for intrinsic, standard-library, provider-backed,
     host-capability, and external calls before lowering

Construction rules.md
   - material construction of conforming canonical IR payloads

Identity and Mapping.md
   - attribution, correspondence, and recoverability law

Schema.md
   - schema posture for canonical JSON IR

schema/
   - machine-checkable schema artifacts

Lowering.md
   - downstream specialization boundary, including provider/capability
     and dependency-closure preparation

Backend contract.md
   - standardized consumer-facing handoff after lowering, including
     manifest-compatible artifact, ABI, provider, host capability, and
     dependency declarations where applicable

This split matters because it prevents one giant document from blurring architectural responsibility.

12. Ownership Quick Check

A fast ownership check is: 

If the question is:
"What does the validated program mean?"
   -> Language/

If the question is:
"What canonical open execution-facing representation exists?"
   -> IR/Execution IR.md

If the question is:
"How does validated meaning become canonical IR?"
   -> IR/Derivation rules.md

If the question is:
"How is a validated library/provider call represented before lowering?"
   -> IR/Library call model.md

If the question is:
"How is conforming canonical IR materially built?"
   -> IR/Construction rules.md

If the question is:
"How are attribution and recoverability preserved?"
   -> IR/Identity and Mapping.md

If the question is:
"How is canonical JSON IR structurally validated?"
   -> IR/Schema.md and IR/schema/

If the question is:
"How does open IR become target-oriented?"
   -> IR/Lowering.md

If the question is:
"What may a downstream backend consumer rely on?"
   -> IR/Backend contract.md

For widget-related execution-facing questions: 

If the question is:
"What is the widget instance source model?"
   -> Expression/

If the question is:
"What is the widget class law?"
   -> Expression/

If the question is:
"What is the host realization package model?"
   -> Expression/

If the question is:
"What execution-facing representation preserves validated
widget interaction meaning?"
   -> IR/

13. Practical Reading Path

A practical reading path for this directory is: 

1. Read this README first
2. Read Execution IR.md
3. Read Derivation rules.md
4. Read Source to FIR scope matrix.md
5. Read Library call model.md
6. Read Identity and Mapping.md
7. Read Construction rules.md
8. Read Schema.md
9. Inspect schema/
10. Read Lowering.md
11. Read Backend contract.md

That order follows the architectural corridor from validated meaning toward later downstream specialization.

A second practical path, when working from conformance or compiler-corridor questions, is: 

Conformance case
   ->
IR/Readme.md
   ->
Derivation rules.md
   ->
Source to FIR scope matrix.md
   ->
Library call model.md
   ->
Identity and Mapping.md
   ->
Schema.md
   ->
Lowering.md
   ->
Backend contract.md

When the concrete question is specifically about widget-object execution-facing preservation, a useful reading sequence is: 

Expression/Widget interaction.md
   ->
IR/Readme.md
   ->
IR/Execution IR.md
   ->
IR/Derivation rules.md
   ->
IR/Identity and Mapping.md
   ->
IR/Lowering.md

14. Status in v0.1

In the current published v0.1 posture, the IR layer is no longer only architectural prose. It already defines a real corridor:

  • validated program meaning,
  • canonical Execution IR derivation,
  • recoverable identity and mapping,
  • material canonical IR construction,
  • canonical JSON schema validation,
  • later lowering and backend-facing handoff, including provider and dependency boundaries where applicable.

This means the repository is already beyond a purely aspirational architecture-only stage. It already exposes the documents needed to reason about a serious compiler-oriented handoff, while keeping LLVM or any other compiler family strictly downstream from the language-owned IR layer.

The active closure direction in v0.1 is therefore not to invent a new IR concept, but to keep tightening:

  • conformance alignment,
  • identity and recoverability law,
  • derivation correctness,
  • schema posture,
  • lowering and backend-contract discipline,
  • the execution-facing preservation corridor for widget-object interaction without collapsing into host realization.

15. Summary

IR/ is the architectural home of canonical open execution-facing representation in FROG.

It begins after validated program meaning and remains upstream from lowering, backend-facing contract, and runtime-private realization.

Its core role is to ensure that execution-facing structure becomes:

  • open,
  • inspectable,
  • attributable,
  • recoverable,
  • schema-checkable in canonical JSON form,
  • ready for disciplined downstream specialization.

The internal split of the directory is intentional:

  • the core open-IR bundle defines the canonical execution-facing layer itself,
  • the downstream IR-adjacent documents define how later stages connect to that layer without replacing it.

That same discipline now applies explicitly to widget-related execution-facing structure:

  • validated widget interaction meaning may be preserved in open IR,
  • but widget package ownership, host realization, SVG rendering logic, and runtime-private UI object structures remain outside the ownership boundary of IR/.

That is the architectural purpose of IR/ in FROG v0.1.