Skip to content

Readme.md

Latest commit

 

History

History
1210 lines (937 loc) · 45.3 KB

Readme.md

File metadata and controls

1210 lines (937 loc) · 45.3 KB

FROG logo

FROG Expression Specification

Canonical source specification for .frog programs and related source-owned widget artifacts
FROG — Free Open Graphical Language

Contents

1. Overview

This directory defines the canonical source specification of FROG — Free Open Graphical Language.

The fundamental executable unit of the language is a FROG. A FROG is a complete graphical dataflow program represented by a structured JSON source file with the .frog extension.

That canonical source file is called the FROG Expression. It is the authoritative, editable, transparent, and version-control-friendly description of a FROG program at the source level.

The purpose of this directory is to define:

  • the canonical top-level structure of a .frog file,
  • the required and optional source sections of that file,
  • the source-level representation of those sections,
  • the source-visible cross-cutting subsystems that appear in canonical source, including the type system, the widget instance model, the widget class contract model, the widget interaction model, the widget-package boundary, and the source-facing representation of structures and local-memory constructs,
  • the structural validity boundary that a canonical .frog source file MUST satisfy before later semantic validation and execution-facing derivation,
  • the source-schema posture under which parts of canonical source shape may be made machine-checkable without collapsing source structure into semantic validation or implementation-private behavior.

This directory is about the authoritative source form of a FROG. It is not the complete runtime architecture, not the complete IDE implementation model, not the complete semantic interpretation of validated programs, and not the open execution-facing IR layer.

This directory also defines the source-owned boundary between the canonical .frog program file and related widget-oriented source artifacts such as .wfrog packages. The canonical program source remains the .frog file. Widget-oriented packages do not replace that role.

Cross-cutting execution semantics are related to this source specification but are not owned here when they belong to validated program meaning. Likewise, optional capability families may appear in executable diagrams, but their normative ownership remains outside Expression/ when they belong to profile specifications rather than to the source format itself.

Source-version interpretation is centralized in Versioning/Readme.md. In particular, the spec_version field follows the repository-wide cumulative version model: later source-format versions should normally extend earlier valid forms rather than silently replace them, unless an explicit breaking boundary is declared. 

Repository architecture around Expression

Expression/   -> canonical source form
Language/     -> validated program meaning
IR/           -> open execution-facing representation
Libraries/    -> intrinsic primitive vocabularies
Profiles/     -> optional standardized capability families
IDE/          -> authoring, observability, debugging, inspection

Expression/ owns source structure and source-visible object shape.
Expression/ owns source well-formedness and structural validity.
Expression/ owns source-schema posture for canonical source.
Expression/ owns the source-side boundary between .frog and related .wfrog packages.
Expression/ does not own validated program meaning.
Expression/ does not own open execution-facing derivation.

2. Why Expression Exists

A graphical language still needs a durable, explicit, tool-independent source form. That is the role of the FROG Expression.

The Expression layer exists so that a FROG program can be:

  • saved as canonical source,
  • read and diffed by humans,
  • versioned in source control,
  • loaded by different tools,
  • checked for source well-formedness and structural validity independently of one IDE implementation,
  • preserved without hidden binary-only authoring state,
  • validated before later semantic interpretation and downstream derivation.

Accordingly, this directory defines how a FROG is serialized, how canonical source becomes structurally valid, and what belongs to the source-owned validation corridor before later semantic interpretation. It does not by itself define every detail of how a FROG is edited, semantically validated by a given tool, derived into IR, lowered, compiled, executed, or deployed. 

Expression/ answers:

- What is in a .frog file?
- Which sections exist?
- Which sections are required?
- How are source objects serialized?
- Which source-level cross-cutting models apply?
- What makes source structurally valid as canonical source?
- What belongs to source-schema posture and machine-checkable source shape?
- How does canonical .frog source relate to source-side .wfrog widget packages?

Expression/ does not answer by itself:

- validated program meaning
- open execution-facing IR structure
- full runtime architecture
- full compiler architecture
- full IDE authoring architecture

This layer exists precisely to keep canonical source explicit without forcing later semantic, runtime, or realization decisions to leak backward into the source format.

3. Scope of this Directory

This directory defines the canonical source format of FROG programs.

It includes:

  • top-level source sections,
  • cross-cutting source subsystems used by multiple sections,
  • source-facing structure and state representation,
  • the source-owned boundary for widget-oriented package references,
  • the source-facing boundary between widget instance shape, widget class contract shape, widget behavior doctrine, and widget realization doctrine,
  • source-schema posture for machine-checkable canonical source shape.

It does not define:

  • the complete runtime architecture,
  • the complete in-memory editable Program Model used by IDE implementations,
  • the complete open execution-facing IR used by toolchains,
  • the complete cross-cutting execution semantics of the language,
  • the complete intrinsic primitive vocabulary of FROG,
  • the complete optional profile surface of FROG,
  • the full repository-wide policy for specification-version transition.

This directory also does not collapse widget class law, widget behavior law, widget realization, or host rendering into the canonical .frog file. Those concerns may be referenced from source, but they remain distinct architectural layers.

Likewise, this directory defines the format and source-owned boundary of .wfrog packages, but the standard primitive widget library published for ecosystem reuse belongs in Libraries/, not in Expression/.

4. Architectural Position

The Expression layer is the source-owned entry point of the representation pipeline. 

canonical .frog source
  -> structural validity
  -> validated program meaning
  -> canonical open execution-facing IR
  -> lowering
  -> backend contract
  -> downstream backend-family consumption

This directory governs the first two items only insofar as they concern source shape and structural validity.

The following distinctions MUST remain explicit:

  • loadable source is not identical to structurally valid canonical source,
  • structurally valid canonical source is not identical to semantically accepted program meaning,
  • canonical source is not identical to execution-facing IR,
  • execution-facing IR is not identical to lowered form,
  • lowered form is not identical to backend contract,
  • backend contract is not identical to one private runtime realization.

The following source-package distinction MUST also remain explicit:

  • the canonical program source artifact is the .frog file,
  • a .wfrog package is a widget-oriented source artifact family,
  • a .wfrog package may be referenced by canonical source,
  • a .wfrog package does not replace the canonical program-owned role of .frog.

The following versioning distinction MUST also remain explicit:

  • the source file's spec_version identifies the source-format compatibility target of that artifact,
  • a .wfrog package may carry its own wfrog_version for widget-package format compatibility,
  • the full repository-wide version-transition policy remains centralized in Versioning/Readme.md.

This positioning is essential for widget closure: runtimes and hosts may interpret canonical source, but they must not silently become the definition of canonical source.

5. Specification Documents

The FROG Expression is defined through the following documents in this directory: 

Expression/
├── Readme.md
│   -> architectural entry point for the canonical source specification
├── Schema.md
│   -> source-schema posture and machine-checkable structural validation boundary
├── schema/
│   └── frog.schema.json
│       -> conservative machine-checkable top-level canonical source schema
├── Metadata.md
│   -> descriptive program metadata and non-executable identification fields
├── Type.md
│   -> canonical type-expression model used across the source format
├── Interface.md
│   -> public typed inputs and outputs of a FROG
├── Connector.md
│   -> graphical perimeter mapping of interface ports when the FROG is reused as a node
├── Diagram.md
│   -> authoritative executable graph as canonical source representation
├── Front panel.md
│   -> optional front-panel composition and user-facing interaction surface
├── Widget.md
│   -> widget instance model, widget identity, roles, class reference, value participation, and source-side package references
├── Widget class contract.md
│   -> class-level widget contract for values, properties, methods, events, parts, access legality, and object-surface exposure
├── Widget interaction.md
│   -> diagram-side widget interaction paths and execution-facing widget access model
├── Widget package (.wfrog).md
│   -> normative package format for .wfrog widget classes, composite publication, realization resources, and bounded behavior publication
├── Widget realization.md
│   -> host-facing realization boundary, visual resources, part-to-visual mapping, and SVG integration
├── Widget behavior.md
│   -> normative behavior boundary for class-owned reaction, declarative rules, bounded expressions, and host-private support
├── Control structures.md
│   -> source-facing representation of canonical control structures
├── State and cycles.md
│   -> source-facing representation of explicit local memory and feedback-cycle formation rules
├── Icon.md
│   -> reusable-node icon representation
├── IDE preferences.md
│   -> optional IDE-facing source metadata and recoverability-oriented authoring preferences
├── Source provenance.md
│   -> optional source-carried authoring provenance, signed attestations, issuer trust, and human review markers
└── Cache.md
    -> optional non-authoritative cache content for tooling convenience

The documents in this directory play four different roles:

  • canonical source scope and ownership matrices,
  • top-level source-section specifications,
  • cross-cutting source subsystems,
  • widget-oriented source package boundary documents,
  • source-schema posture and machine-checkable structural support artifacts.

5.1 Top-level source-section specifications

Some documents define dedicated top-level source sections such as:

  • metadata,
  • interface,
  • connector,
  • diagram,
  • front_panel,
  • icon,
  • ide,
  • cache.

Canonical source scope.md provides the compact cross-section view of this ownership model. It should be read before drilling into individual section documents when the question is whether a source fact is required, optional, descriptive metadata, diagram-owned, front-panel-owned, binding source, or excluded from executable source meaning.

5.2 Cross-cutting source subsystems

Other documents define cross-cutting source subsystems used throughout the source format. In particular:

  • Type.md defines canonical value-type expressions and source-level type rules used throughout the source format.
  • Widget.md defines the widget instance model used inside front_panel.
  • Widget class contract.md defines the class-level widget contract behind standardized widget-object surfaces, including part ownership, member legality, mutability, and access constraints.
  • Widget interaction.md defines how executable diagrams may interact with widgets through standardized diagram-level interaction mechanisms.
  • Control structures.md and State and cycles.md define source-facing representation rules that participate in later semantic interpretation but must appear explicitly in canonical source.

Source provenance is also a cross-cutting source-carried subsystem. Source provenance.md defines the optional ide.provenance object used to record authoring, generation, import, modification, and human-review attestations for source-visible objects without changing executable meaning.

5.3 Widget-oriented source package boundary documents

The widget-oriented package documents define how canonical source relates to source-side widget packages.

  • Widget package (.wfrog).md defines the .wfrog artifact family, its package structure, its package kinds, and the publishable format for widget classes, composite widgets, realization resources, and bounded behavior surfaces.
  • Widget realization.md defines the host-facing realization boundary, including part-to-visual mapping and SVG integration.
  • Widget behavior.md defines the behavior doctrine used by widget classes and related package content, including intrinsic behavior, declarative rules, bounded expressions, and host-private support boundaries.

These documents do not turn widget packages into top-level canonical program files. They define how source may reference those packages while preserving ownership boundaries.

5.4 Source-schema posture

Schema.md and the files under schema/ define the conservative machine-checkable posture of canonical source shape.

They do not replace semantic validation. They provide machine-checkable support for source-level structure where that structure can be checked without collapsing later interpretation layers.

6. What a .frog File Describes

A canonical .frog file describes one complete FROG program as source.

At minimum, it describes:

  • its identity and descriptive metadata,
  • its public typed boundary,
  • its authoritative executable diagram.

It may additionally describe:

  • its reusable-node connector,
  • its front-panel composition,
  • its icon,
  • its IDE-facing source metadata,
  • its non-authoritative cache data.

When a front panel is present, the .frog file may also reference widget-oriented packages needed to interpret widget class law, widget bounded behavior, or host-facing realization. Even in those cases, the .frog file remains canonical program source, not a container for all widget package contents.

The .frog file is canonical source, not compiled output, not IR, and not one implementation's private runtime representation.

7. Representation Levels

The repository architecture distinguishes several layers: 

canonical .frog source
  -> structural validity
  -> validated language meaning
  -> open execution-facing IR
  -> lowering
  -> backend contract
  -> downstream backend-family consumption

This directory governs the first two items only insofar as they concern source shape and structural validity.

The following distinctions MUST remain explicit:

  • loadable source is not identical to structurally valid canonical source,
  • structurally valid canonical source is not identical to semantically accepted program meaning,
  • canonical source is not identical to execution-facing IR,
  • execution-facing IR is not identical to lowered form,
  • lowered form is not identical to backend contract,
  • backend contract is not identical to one private runtime realization.

The following source-artifact distinction MUST also remain explicit:

  • canonical program source is not identical to widget-package source,
  • widget-package source is not identical to host-private rendering logic,
  • visual assets are not identical to widget class law,
  • runtime-private convenience is not identical to language-owned object law.

These distinctions are especially important in the widget corridor because source shape, class law, behavior law, realization resources, runtime interpretation, and host realization must remain inspectably separate.

8. File Tree and Artifact Families

A canonical .frog source file is a single JSON document whose internal sections refer to source-level artifact families.

At the top level, canonical source remains intentionally compact.

  • type information is embedded locally through canonical type expressions,
  • widget instances are embedded inside front_panel when a front panel is present,
  • widget interactions are expressed inside diagram,
  • structure and state constructs are embedded where they naturally belong in the source graph,
  • widget-oriented package references may appear where relevant without becoming separate top-level program sections.
Top-level simplicity rule

No dedicated top-level:
- types
- widgets
- widget_interactions
- control_structures
- state_model
- widget_packages

These concerns are embedded where they naturally belong.

The broader source artifact family therefore includes:

  • the canonical program file .frog,
  • optional referenced .wfrog packages for widget classes, composite widget definitions, realization resources, behavior publication, or bundle content,
  • optional visual assets such as SVG where referenced by widget realization content.

The future standardized primitive widget families that make up the reusable front-panel baseline are expected to be published through Libraries/ using these artifact families, rather than being redefined inside this architectural directory.

9. File Types

The canonical editable source artifact of a FROG program is a file with the .frog extension.

That file MUST contain canonical JSON source conforming to the structural rules defined by this directory.

The widget-oriented package family uses the .wfrog extension. A .wfrog package is a structured JSON widget-oriented artifact that may be referenced by canonical source.

A .wfrog package is not a second canonical program file. It is a related source artifact family with its own typed package kinds and version line.

Repository support artifacts such as schema files, examples, conformance material, or implementation workspaces are not themselves canonical .frog source unless explicitly stated otherwise.

10. Top-Level JSON Structure

At the top level, a canonical .frog source file is a JSON object.

The top-level object contains required and optional sections whose detailed structure is owned by the companion documents in this directory.

Conceptually: 

{
  "spec_version": "...",
  "metadata": { ... },
  "interface": { ... },
  "diagram": { ... },

  "front_panel": { ... },
  "connector": { ... },
  "icon": { ... },
  "ide": { ... },
  "cache": { ... }
}

This top-level simplicity is deliberate. Many cross-cutting subsystems participate in canonical source without becoming separate top-level sections.

Widget-oriented package references, when present, appear inside the relevant source-owned structures such as widget instances in the front panel. They do not become standalone top-level program sections merely because they are important.

11. Section Presence Rules

A canonical .frog source file MUST contain:

  • spec_version,
  • metadata,
  • interface,
  • diagram.

A canonical .frog source file MAY additionally contain:

  • front_panel,
  • connector,
  • icon,
  • ide,
  • cache.

The front_panel section is optional. It SHOULD be present when the FROG intentionally includes a user-facing interaction layer. When absent, the FROG is interpreted as a program with no serialized front-panel composition.

The connector section is optional. It SHOULD be present when the FROG is intended to be reused as a graphical node inside another diagram.

Optional sections MUST NOT modify the authoritative execution semantics established by validated program meaning. 

Presence summary

MUST:
- spec_version
- metadata
- interface
- diagram

MAY:
- connector
- front_panel
- icon
- ide
- cache

The presence of spec_version is the source-level anchor for cumulative source evolution. Later source-format versions should normally extend earlier valid forms rather than silently invalidate them, as governed centrally in Versioning/Readme.md.

Widget-oriented package references are governed by the relevant source structures that use them. Their presence does not create new mandatory top-level sections in canonical .frog source.

12. Sections Overview

12.1 Metadata

Required section defining identity, documentation, authorship, and related descriptive information.

Detailed specification: Metadata.md

12.2 Interface

Required section defining the public typed inputs and outputs of the FROG. All declared types MUST use canonical FROG type expressions.

Detailed specifications: Interface.md, Type.md

12.3 Connector

Optional section defining the graphical mapping of interface ports when the FROG is reused as a node. The connector never defines new logical ports.

Detailed specification: Connector.md

12.4 Diagram

Required section defining the executable dataflow graph of the FROG. The diagram contains nodes, edges, dependencies, regions, boundaries, and annotations as source-level constructs. It is the authoritative source-level execution structure of the program.

Detailed specifications: Diagram.md, Type.md, Widget interaction.md, the source-facing companion documents Control structures.md and State and cycles.md, the normative semantic documents in Language/, the relevant intrinsic primitive-library specifications in Libraries/, and any relevant optional standardized capability specifications in Profiles/.

12.5 Front Panel

Optional section defining the user interaction layer of the FROG through widget instances, layout, and related UI composition data.

When absent, the canonical source defines no serialized front-panel composition for that FROG.

The front panel defines widget containment and panel-side composition. It does not by itself define the full widget object contract, the full executable widget interaction model, or the authoritative executable graph.

Detailed specifications: Front panel.md, Widget.md, Widget class contract.md, Widget package (.wfrog).md, Widget realization.md, Widget behavior.md

12.6 Icon

Optional section containing the icon used by tools when the FROG is represented as a reusable node.

Detailed specification: Icon.md

12.7 IDE Preferences

Optional section containing IDE-facing preferences and recoverability metadata serialized with the FROG itself. This section belongs to the FROG Expression because a FROG behaves as a durable editable program unit and may embed source-level IDE preferences together with non-authoritative authoring recoverability aids.

Runtimes and other execution-facing systems MUST ignore this section for execution semantics.

Detailed specification: IDE preferences.md

12.8 Cache

Optional section containing derived, non-authoritative tooling data used to accelerate workflows.

Detailed specification: Cache.md 

Section role summary

metadata    -> descriptive identity
interface   -> public typed boundary
connector   -> graphical node-side projection of interface
diagram     -> authoritative executable graph
front_panel -> optional user interaction surface
icon        -> reusable-node icon
ide         -> non-authoritative IDE-facing metadata
cache       -> non-authoritative tooling cache

13. Cross-Cutting Subsystems

13.1 Type System

FROG defines a normative built-in type system described in Type.md.

This subsystem applies wherever values are declared, connected, constrained, validated, or coerced, including:

  • interface ports,
  • diagram ports and edge validation,
  • structure boundaries,
  • typed configuration values such as default or initial,
  • widget primary values,
  • typed widget members.

The type system is cross-cutting. It is not represented as a dedicated required top-level section.

13.2 Widget Instance Model

FROG defines a normative widget instance model described in Widget.md.

A widget is not merely a drawing. At source level, it is a structured UI object instance with identity, class reference, role, optional typed value, persisted instance-side properties where allowed, and optional source-side references to widget-oriented packages.

The widget instance model is cross-cutting. It governs widget instances contained inside front_panel when that section is present.

13.3 Widget Class Contract Model

FROG defines a normative class-level widget contract model described in Widget class contract.md.

This model governs the stable object-surface contract behind widget classes, including:

  • class identity,
  • member categories,
  • part ownership,
  • property readability and writability,
  • method invocability,
  • event exposure,
  • mutability boundaries,
  • addressing legality.

This class-level contract remains distinct from:

  • front-panel composition,
  • diagram-side executable widget interaction,
  • one private IDE implementation strategy,
  • one private runtime realization.

13.4 Widget Interaction Model

FROG defines a normative widget interaction model described in Widget interaction.md.

This model governs diagram-level interaction with widgets through standardized mechanisms such as:

  • natural value participation through widget_value,
  • object-style widget access through widget_reference,
  • property read,
  • property write,
  • method invocation,
  • event observation where supported by the interaction corridor.

These interactions are represented inside the executable diagram rather than as a dedicated top-level source section.

The current source-level widget interaction model already uses standardized primitive identifiers in the frog.ui.* namespace. Future intrinsic UI primitive specifications and future profile-based capability expansions MUST remain consistent with that source-level interaction model and with the class-level member contracts declared for widgets.

13.5 Widget Package Boundary

FROG defines a source-owned widget package boundary described in Widget package (.wfrog).md, Widget realization.md, and Widget behavior.md.

This boundary governs how canonical source may refer to widget-oriented packages without collapsing architectural layers.

In particular:

  • .frog remains the canonical program source file,
  • .wfrog defines widget-oriented package artifacts,
  • widget class law is not the same thing as widget realization,
  • widget realization is not the same thing as host-private rendering logic,
  • widget behavior law is not the same thing as unrestricted arbitrary host code,
  • SVG is a visual asset layer, not hidden executable truth.

The standardized primitive widget families intended for ecosystem-wide reuse are expected to be published in Libraries/ on top of this boundary, not inside this boundary document set itself.

13.6 Control-Structure and Local-Memory Source Dependencies

FROG includes source-facing representation rules for structures, explicit local memory, and feedback-cycle formation inside this directory:

  • Control structures.md defines the source-facing representation of structure families and their serialized form,
  • State and cycles.md defines the source-facing representation of explicit local-memory elements and feedback-cycle formation constraints.

The structural serialization of those constructs belongs here because they must appear explicitly in canonical source. Their validated execution meaning belongs to Language/. 

Cross-cutting ownership

Serialized shape of structures/cycles   -> Expression/
Execution meaning of structures/cycles  -> Language/
Intrinsic primitive meaning             -> Libraries/
Optional capability meaning             -> Profiles/
Widget instance-side source shape       -> Expression/
Widget class-side contract shape        -> Expression/
Diagram-side widget interaction shape   -> Expression/
Source-side widget package boundary     -> Expression/
Validated meaning of widget interaction -> Language/ and related primitive/profile ownership

13.7 Source Provenance Boundary

FROG defines an optional source provenance boundary in Source provenance.md. Its standardized home is ide.provenance, where tools may carry attestations for nodes, edges, structures, widgets, interface objects, annotations, changesets, or whole-document review states.

This boundary is deliberately non-executable. Missing provenance means unknown or unattested, not automatically AI-generated. Valid provenance may support inspection, review, and accountability, but it MUST NOT define canonical source meaning, validated program meaning, FIR derivation, lowering, backend handoff, or runtime execution semantics. 

Source provenance boundary

ide.provenance
  -> authoring / generation / review evidence
  -/-> executable meaning

diagram / interface / front_panel
  -> source objects that may be attested
  -> remain authoritative for their own source roles

14. .frog and .wfrog Boundary

The canonical program source artifact of FROG is the .frog file.

The widget-oriented package artifact family uses the .wfrog extension.

This boundary is intentional and normative.

  • .frog owns canonical program source.
  • .frog owns program sections such as metadata, interface, diagram, and optional front_panel.
  • .frog owns widget instances used by the program when a front panel is present.
  • .wfrog may own widget class package content, composite widget package content, widget realization package content, widget behavior publication content, or bundle content.
  • .wfrog does not replace the canonical program-owned role of .frog.

The following distinctions MUST remain explicit: 

canonical program source      != widget-oriented package
widget instance declaration   != widget class definition
widget class law              != widget realization
widget behavior law           != unrestricted host code
widget semantics              != SVG visual asset
runtime interpretation        != language ownership
one runtime implementation    != FROG widget definition

A canonical .frog file MAY reference .wfrog packages through source-owned structures such as widget instances. Those package references must remain explicit and reviewable.

15. Interface, Connector, Diagram, and Front Panel

15.1 Interface

The interface defines the public typed boundary of a FROG.

It answers:

  • which public inputs exist,
  • which public outputs exist,
  • what their types are,
  • what their source-level metadata is.

15.2 Connector

The connector defines how those public interface ports are projected graphically when the FROG is reused as a node inside another diagram.

The connector does not create new interface meaning. It is a graphical perimeter mapping of already-declared interface ports.

15.3 Diagram

The diagram is the authoritative executable graph of the FROG.

It defines:

  • nodes,
  • edges,
  • dependencies,
  • regions,
  • explicit state participation where applicable,
  • diagram-side widget interaction when present.

The diagram remains the executable authority. Front-panel composition and connector appearance do not replace it.

15.4 Front Panel

When present, the front panel defines widgets, layout, and visual interaction for the FROG itself. It does not define the public API and it does not replace the executable graph.

Accordingly:

  • a front-panel widget does not create a public interface port by itself,
  • a control widget is not automatically a public input,
  • an indicator widget is not automatically a public output.

Any relationship between public interface behavior and front-panel behavior MUST be represented through the diagram. 

Do not collapse these into one concept

interface   != front_panel
connector   != interface
diagram     != front_panel
diagram     is the executable authority

The following distinction MUST also remain explicit: 

front_panel             -> widget containment and panel composition
widget instance model   -> instance-side object shape
widget class contract   -> class-side member legality and exposure
widget interaction      -> diagram-side executable object access
widget packages         -> related source-side package artifacts

16. Source Well-Formedness and Structural Validity

A canonical .frog file MUST first be loadable as source.

That is not yet sufficient for structural validity.

Structural validity concerns whether the source:

  • contains the required top-level sections,
  • uses the correct source-owned section shapes,
  • uses canonical field structures where required,
  • respects source-level identity and containment rules,
  • respects source-level addressing constraints for cross-cutting subsystems such as widget interaction,
  • uses source-owned package references in structurally valid locations when such references are present.

Structural validity does not by itself establish the full validated meaning of the program.

Structural validity also does not by itself define cross-version policy. The repository-wide cumulative version model and related transition doctrine remain centralized in Versioning/Readme.md.

Likewise, structural validity of source-owned package references does not by itself establish the full semantic validity of widget law, realization law, widget behavior law, or runtime support claims.

17. Execution Relevance, Validation, and Derivation Boundary

Expression/ governs canonical source before semantic validation and before open execution-facing derivation.

This means:

  • source shape is owned here,
  • source-level cross-cutting subsystems needed for serialization are owned here,
  • validated meaning is owned later,
  • IR derivation is owned later,
  • lowering and backend handoff are owned later.

Some source constructs are clearly execution-relevant, including:

  • diagram connectivity,
  • structure boundaries,
  • explicit local memory,
  • widget interaction expressed in the diagram,
  • source-visible widget-package references that later guide widget-class, widget behavior, and realization interpretation.

Even so, Expression/ owns them only as source representation and structural validity. Their validated meaning belongs elsewhere.

18. Canonical Formatting and Ordering

Canonical source SHOULD remain stable, explicit, and diff-friendly.

Tools SHOULD preserve:

  • stable section ordering,
  • stable object key ordering where the relevant specification defines one,
  • stable identity fields,
  • stable explicitness over hidden implicit reconstruction where practical.

Non-authoritative IDE or cache sections MUST NOT be allowed to obscure the authoritative source meaning of required executable sections.

Likewise, source-owned references to widget packages SHOULD remain explicit and readable rather than being hidden inside one implementation's private resolution metadata.

19. Normative Terminology

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as normative requirement language.

When this document describes ownership boundaries, those boundaries are normative architectural boundaries unless explicitly stated otherwise.

20. Status

This directory defines the canonical source layer of the published FROG specification.

Some parts of the source model are intentionally conservative so that:

  • canonical source remains stable,
  • structural validity remains machine-checkable where appropriate,
  • later semantic and execution-facing layers can evolve without collapsing back into private tool behavior,
  • later source-format versions can remain cumulative extensions of earlier valid forms rather than silent replacements.

The active closure direction for the widget architecture in this layer is to keep the canonical program source compact while making the source-owned boundary to widget-oriented .wfrog packages explicit, inspectable, extensible, and multi-runtime compatible.

The immediate downstream closure direction is to use that boundary to support a minimal standardized widget primitive baseline in Libraries/, from which richer front-panel ecosystems and developer-defined composite widgets can be built.

21. License

See the repository-level license information for the licensing terms governing this specification.