Skip to content

Execution model.md

Latest commit

 

History

History
686 lines (546 loc) · 25.1 KB

Execution model.md

File metadata and controls

686 lines (546 loc) · 25.1 KB

FROG logo

🐸 FROG Execution Model Specification

Normative execution-model concepts for validated FROG programs
FROG — Free Open Graphical Language

Contents

1. Overview

This document defines the core execution-model concepts of the FROG language. It specifies the minimal language-level objects and relations needed to describe what a validated FROG means when it executes, independently of any particular IDE, runtime implementation, compiler pipeline, transport protocol, or execution target.

This document is not the canonical source specification. It does not define how a FROG is serialized in a .frog file. It also does not define IDE-facing event delivery, debugging commands, probe windows, watch views, or runtime-internal scheduler design.

Instead, this document defines the stable execution-model vocabulary that other specifications rely on. That vocabulary includes:

  • the validated executable graph,
  • the live execution instance,
  • source identity,
  • activation,
  • execution context,
  • semantic execution milestones,
  • committed source-level state,
  • runtime freedom constrained by observable semantic equivalence.

These concepts form the language-level baseline on top of which observability, debugging, probes, watch behavior, runtime profiles, and future lowering layers MAY be defined without moving semantic ownership out of Language/.

2. Goals

This document has the following goals:

  • define the minimal execution-model concepts that apply across validated FROG programs,
  • give source-aligned execution meaning a normative home in Language/,
  • separate language-level execution meaning from IDE-facing observation and control behavior,
  • remain compatible with multiple runtimes, schedulers, transports, and execution targets,
  • provide a durable semantic basis for later specifications such as execution observability, debugging boundaries, and execution profiles.

3. Relation with Other Specifications

This document depends on the following specifications:

  • Readme.md for the repository-wide architecture and layering,
  • Language/Readme.md for the ownership boundary of Language/,
  • Language/Control structures.md for the normative execution semantics of case, for_loop, and while_loop,
  • Language/State and cycles.md for the normative execution semantics of explicit local memory and valid feedback cycles,
  • Expression/Diagram.md for the canonical source representation of the validated executable graph,
  • Expression/Control structures.md for the canonical representation of structure families, regions, and structure-owned boundaries,
  • Expression/State and cycles.md for the canonical representation of local-memory constructs and cycle-facing source constraints,
  • IDE/Execution observability.md for the IDE-facing projection of execution activity,
  • IDE/Debugging.md for user-facing control semantics layered over language-defined execution boundaries,
  • IDE/Probes.md and IDE/Watch.md for IDE-managed inspection constructs that consume committed source-level observations.

This document MUST NOT contradict those specifications. If a conflict appears:

  • Expression/ remains authoritative for canonical source representation and source-visible identity,
  • Language/ remains authoritative for normative execution meaning,
  • Libraries/ remain authoritative for primitive identity, primitive-local behavior, ports, and required metadata,
  • IDE/ remains authoritative only for IDE-facing observation, control, presentation, and tooling behavior.

This document intentionally defines execution-model concepts without defining the full pause model, safe observation boundaries, or safe debug-stop boundaries. Those topics belong to the companion document: Language/Execution control and observation boundaries.md.

4. Scope for v0.1

For FROG v0.1, this document standardizes the minimal language-level execution-model core needed by the rest of the repository. At minimum, this includes:

  • what a validated executable graph is at execution time,
  • what a live execution instance is,
  • how source-level execution identity is preserved,
  • what an activation is,
  • what an execution context is,
  • which execution milestones exist at the semantic level,
  • what committed source-level state means,
  • how runtime freedom is constrained by observable semantic equivalence.

For v0.1, this document does not standardize:

  • a runtime-internal scheduler architecture,
  • a transport protocol or event-stream protocol,
  • an IDE command model,
  • pause, resume, or stepping commands,
  • safe observation points or safe debug stops,
  • a full runtime profile model,
  • a lowering or execution-IR contract,
  • distributed execution semantics,
  • asynchronous execution semantics beyond the baseline model defined here.

5. Validated Executable Graph and Live Execution Instance

5.1 Validated executable graph

A validated executable graph is the language-level executable meaning of a FROG after:

  • canonical source parsing,
  • structural validation,
  • type validation,
  • primitive and structure-family validation,
  • cycle-validity validation,
  • all other v0.1 validation rules required by the relevant specifications.

A validated executable graph MUST be source-aligned. Its executable objects MUST remain attributable to source-visible objects defined in the canonical FROG Expression.

A validated executable graph is not an IDE view, not a runtime trace, and not an execution log. It is the validated language-level executable object whose meaning is then realized by one or more live executions.

5.2 Live execution instance

A live execution instance is one running realization of one validated executable graph. A live execution instance owns its own dynamic execution history.

At minimum, a live execution instance conceptually includes:

  • one validated executable graph as its semantic basis,
  • its own dynamic activation history,
  • its own dynamic execution contexts,
  • its own local-memory state where local memory exists,
  • its own nested sub-FROG invocation history where sub-FROG calls occur.

A live execution instance is the semantic object over which later specifications may define:

  • observation,
  • debug control,
  • diagnostics,
  • runtime integration,
  • execution profiles.

5.3 Instance independence

Distinct live execution instances of the same validated executable graph MUST remain semantically independent unless a stricter future profile explicitly standardizes a shared external execution resource.

In particular, for base v0.1:

  • local memory MUST NOT be implicitly shared across independent live execution instances,
  • dynamic activation identity MUST be instance-relative,
  • execution context MUST be interpreted relative to one specific live execution instance,
  • committed source-level observations MUST be attributable to one specific live execution instance.

6. Source Identity

Observable and inspectable execution meaning MUST remain attributable to stable source-level identity. A runtime MAY use internal identifiers, compiled forms, optimized graphs, or backend-specific scheduling objects, but those implementation details MUST remain projectable back to source-level objects.

For v0.1, source-level execution identity MAY correspond to objects such as:

  • a node,
  • an edge,
  • a structure instance,
  • a structure-owned region,
  • a sub-FROG call site,
  • a local-memory primitive instance,
  • a source-level port or terminal when a stricter profile requires that granularity.

Two distinct source-level objects MUST NOT become semantically indistinguishable merely because a runtime reuses internal scheduling or storage mechanisms.

Conversely, multiple internal runtime objects MAY correspond to one source-level object, provided that the externally meaningful execution identity remains source-aligned and semantically consistent.

7. Activation and Execution Context

7.1 Activation

An activation is one dynamic occurrence of execution activity associated with a source-aligned executable object inside one live execution instance.

For v0.1, the language-level notion of activation is intentionally generic. It applies, as relevant, to:

  • a node activation,
  • a structure activation,
  • a region activation,
  • a loop iteration activation,
  • a sub-FROG invocation activation.

A source-level object MAY activate:

  • zero times,
  • exactly once,
  • multiple times sequentially,
  • multiple times under distinct nested dynamic scopes,
  • multiple times across repeated structure or sub-FROG activations.

Therefore, source identity alone is not sufficient to describe dynamic execution meaning. Dynamic activity MUST also be attributable to an execution context.

7.2 Execution context

An execution context is the dynamic path under which one activation or one committed source-level observation occurs inside one live execution instance.

For v0.1, an execution context MAY include:

  • the live execution instance identity,
  • sub-FROG invocation nesting,
  • structure nesting,
  • the selected region identifier when a structure owns alternative regions,
  • the current loop iteration index when applicable,
  • the current activation identifier for the relevant executable object.

An execution context MUST be rich enough to distinguish semantically different dynamic occurrences of the same source-level object.

Accordingly, the following situations MUST remain distinguishable when they are semantically distinct:

  • two different iterations of the same loop body,
  • two different invocations of the same sub-FROG call site,
  • activity inside a selected case region versus activity outside that region,
  • caller-level activity versus callee-level activity,
  • multiple dynamic activations of the same source node within one live execution instance.

A context MAY be represented differently by different runtimes. Its internal encoding is not standardized here. Its semantic role is standardized.

7.3 Illustrative context shape

The following diagram illustrates the semantic idea of execution context. It is illustrative only. It does not define a mandatory serialized representation. 

instance I42
└── subfrog call site: compute_gain
    └── while_loop body
        └── iteration = 3
            └── case region = "locked"
                └── node activation: n17 / activation 2

In this example, the node identity alone is insufficient. The full dynamic meaning depends on the instance, call path, structure path, selected region, iteration, and local activation occurrence.

8. Semantic Execution Milestones

8.1 General rule

This document standardizes semantic execution milestones, not an IDE event protocol. A runtime MAY expose those milestones through events, callbacks, traces, logs, polling APIs, or equivalent mechanisms, but the language-level meaning MUST remain stable.

A stricter specification MAY define canonical observable event names or payload categories. That later projection MUST preserve the semantic milestones defined here.

8.2 Node milestones

For a source-aligned executable node, the following semantic milestones MAY exist where relevant to the execution model or to stricter derived specifications:

  • the node becomes executable or ready,
  • the node activation begins,
  • the node activation completes,
  • the node activation terminates because of an execution fault.

This document does not require every runtime to expose each milestone directly. It defines that these milestones are semantically meaningful distinctions when higher-level specifications rely on them.

8.3 Edge value availability

When a source-level edge receives a value that becomes semantically available to downstream execution, that availability constitutes a semantic milestone.

This milestone is language-level because it belongs to source-aligned execution meaning, even if an implementation chooses different buffer strategies, queue strategies, batching strategies, or transport strategies internally.

8.4 Structure and region milestones

For standardized control structures, semantic milestones MAY include:

  • structure activation begins,
  • a region becomes selected,
  • a selected region begins execution,
  • a loop iteration begins,
  • a loop iteration ends,
  • the structure activation completes.

These milestones do not replace the more specific semantics defined in Language/Control structures.md. They provide the shared execution-model vocabulary needed when such activity must later be observed, debugged, or diagnosed in a source-aligned way.

8.5 Local-memory milestones

For explicit local memory, semantic milestones MAY include:

  • the stored state is read as part of one activation,
  • the stored state is updated according to the primitive-local state rule,
  • the resulting committed local-memory state becomes the new state for later relevant activations.

These milestones do not replace the normative state semantics defined in Language/State and cycles.md. They provide the execution-model vocabulary needed when local memory is later projected to observation, probes, or watches.

8.6 Sub-FROG milestones

For a subfrog call site, semantic milestones MAY include:

  • the call-site activation begins,
  • the callee instance or nested execution scope is entered,
  • the callee completes,
  • the caller-side call-site activation completes or faults accordingly.

A runtime MAY expose only caller-level visibility in a minimal profile. A stricter profile MAY expose nested callee-level activity. In either case, the language-level model requires that nested dynamic meaning remain attributable through execution context.

9. Committed Source-Level State

9.1 Definition

Committed source-level state is the source-aligned execution state that is semantically valid to treat as an actual state of a live execution instance at the language level.

Committed source-level state exists to distinguish:

  • semantic state that is already valid to interpret at the source level,
  • internal runtime-transient state that MAY exist implementation-wise but is not yet semantically committed for source-level interpretation.

A runtime MAY use internal transient buffers, partial scheduling queues, temporary values, speculative internal states, or backend-specific staging mechanisms. Those internal details do not automatically become committed source-level state.

9.2 Committed values and snapshots

For v0.1, the following are examples of what MAY become committed source-level state when semantically valid:

  • a value that is source-level meaningful on an edge,
  • a value that is source-level meaningful at a node port,
  • a selected structure region,
  • a completed loop iteration milestone,
  • a local-memory state snapshot after a valid state update,
  • another source-aligned state snapshot defined by a stricter profile.

When a later specification refers to a last-known committed observation, last-known committed value, or committed state snapshot, that wording MUST be interpreted relative to the notion defined here.

Committed source-level state is always interpreted relative to:

  • one live execution instance,
  • one source-level target,
  • one relevant execution context.

9.3 What this document does not define

This document defines the notion of committed source-level state, but it does not yet define:

  • the full safe-observation boundary model,
  • the full pause-consistent snapshot model,
  • the full safe-debug-stop model,
  • the exact control boundaries at which a runtime must pause or may expose a coherent snapshot.

Those boundary rules belong to the companion document Language/Execution control and observation boundaries.md.

10. Runtime Freedom and Observable Equivalence

Different runtimes MAY use different:

  • threads,
  • queues,
  • buffers,
  • memory layouts,
  • scheduling strategies,
  • backend partitioning strategies,
  • compiled or lowered internal forms.

However, this freedom is constrained. The source-aligned execution meaning of a validated FROG MUST remain equivalent across conforming implementations.

In particular, conforming runtimes MUST NOT disagree about:

  • which source-level object an execution activity belongs to,
  • whether distinct execution contexts are semantically distinct,
  • whether a sub-FROG activation belongs to the caller instance through the relevant execution context,
  • which structure region is selected for one structure activation,
  • whether a local-memory update changes the committed state for later relevant activations,
  • what counts as source-level committed meaning once the relevant semantic milestone has occurred.

This separation allows backend freedom without semantic fragmentation of the language.

11. Validation Rules

Implementations MUST enforce the following language-level rules:

  • every live execution instance MUST correspond to one validated executable graph,
  • every source-aligned execution observation or inspection result MUST remain attributable to stable source identity,
  • dynamic execution meaning MUST remain attributable to an execution context whenever source identity alone is insufficient,
  • distinct live execution instances MUST remain semantically independent unless a stricter future profile explicitly defines otherwise,
  • committed source-level state MUST NOT be confused with runtime-internal transient implementation state,
  • runtime freedom MUST preserve source-aligned semantic equivalence.

Implementations SHOULD additionally make it possible to retain enough identity and context information to support:

  • source-aligned observability,
  • source-aligned debugging,
  • source-aligned probes and watches,
  • diagnostic attribution at the level of nodes, structures, regions, and sub-FROG call sites.

12. Out of Scope for v0.1

  • the exact safe-observation model,
  • the exact safe-debug-stop model,
  • the full pause/resume state machine,
  • the full fault/abort control-boundary model,
  • a mandatory runtime event transport,
  • a mandatory event payload schema,
  • a mandatory timestamp model,
  • a mandatory value-serialization model,
  • distributed execution semantics,
  • asynchronous task orchestration semantics,
  • execution-IR contracts,
  • compiler-lowering contracts,
  • runtime capability and security profiles.

13. Summary

This document defines the execution-model vocabulary that belongs normatively to Language/.

  • a validated FROG executes as a validated executable graph,
  • a live execution instance is one running realization of that graph,
  • execution meaning MUST remain attributable to stable source identity,
  • dynamic activity MUST also remain attributable to execution context whenever source identity alone is insufficient,
  • semantic execution milestones exist independently of any one observability protocol,
  • committed source-level state distinguishes semantically valid source-level meaning from runtime-internal transient state,
  • runtime freedom is allowed only when source-aligned semantic equivalence is preserved.

This gives FROG a stable language-level execution-model foundation on top of which observability, debugging, probes, watches, runtime profiles, and future lowering layers can be specified without collapsing architectural ownership.

14. License

This specification is part of the FROG repository and is licensed under the repository license.