docs: clarify end-to-end execution pipeline

Examples/05_bounded_ui_accumulator/Execution pipeline.md

@@ -0,0 +1,109 @@
+<p align="center">
+  <img src="../../FROG logo.svg" alt="FROG logo" width="140" />
+</p>
+
+<h1 align="center">Example 05 Execution Pipeline</h1>
+
+<p align="center">
+  <strong>Concrete source, FIR, lowering, runtime, widget, and LLVM-oriented proof corridor for Example 05</strong><br/>
+  <em>FROG — Free Open Graphical Language</em>
+</p>
+
+<hr/>
+
+<h2>Purpose</h2>
+
+<p>
+This page explains how <code>Examples/05_bounded_ui_accumulator</code> runs through the current public reference corridor.
+It is a concrete companion to <a href="./Readme.md">Example 05 — Bounded UI Accumulator</a>.
+</p>
+
+<p>
+The page is descriptive and non-normative. It does not make LLVM part of FROG semantics, does not define a production runtime, and does not turn one hosted UI into the FROG language runtime identity.
+</p>
+
+<hr/>
+
+<h2>Artifact Flow</h2>
+
+<pre><code>Examples/05_bounded_ui_accumulator/main.frog
+  -&gt; loadability
+  -&gt; structural validation
+  -&gt; semantic validation
+  -&gt; Examples/05_bounded_ui_accumulator/main.fir.json
+  -&gt; Examples/05_bounded_ui_accumulator/main.lowering.json
+  -&gt; Implementations/Reference/ContractEmitter/examples/05_bounded_ui_accumulator.reference_host_runtime_ui_binding.contract.json
+  -&gt; Implementations/Reference/Runtime/acceptance/example05_runtime_family.acceptance.json
+  -&gt; Implementations/Reference/LLVM/examples/05_bounded_ui_accumulator/module.ll
+  -&gt; Implementations/Reference/LLVM/examples/05_bounded_ui_accumulator/kernel.ll
+  -&gt; Implementations/Reference/LLVM/examples/05_bounded_ui_accumulator/native_kernel_manifest.json
+  -&gt; runtime bridge and hosted front-panel snapshot</code></pre>
+
+<hr/>
+
+<h2>Two Branches Joined by the Runtime</h2>
+
+<h3>Diagram and computation branch</h3>
+
+<pre><code>main.frog diagram
+  -&gt; validated program meaning
+  -&gt; FIR / Execution IR
+  -&gt; lowering
+  -&gt; backend contract
+  -&gt; LLVM-oriented module / native proof where applicable
+  -&gt; runtime call boundary</code></pre>
+
+<p>
+The diagram branch owns the executable dataflow path. In this example, the bounded accumulator computes the result from the public input and explicit stateful iteration shape.
+</p>
+
+<h3>Front-panel and widget branch</h3>
+
+<pre><code>main.frog front_panel
+  -&gt; ui/accumulator_panel.wfrog
+  -&gt; Libraries/Realizations/Default/assets/numeric/templates/numeric_rectangular.svg
+  -&gt; hosted numeric control and indicator realization
+  -&gt; runtime widget bindings</code></pre>
+
+<p>
+The front-panel branch owns the visible widget layout and realization-facing path. The <code>.wfrog</code> package and SVG asset support realization; they do not replace <code>.frog</code> as the program source and do not define hidden language semantics.
+</p>
+
+<hr/>
+
+<h2>Runtime Role</h2>
+
+<p>
+The runtime is the orchestration consumer at the point where the two branches meet.
+For this example, the runtime-family corridor may:
+</p>
+
+<ul>
+  <li>consume the host-runtime UI-binding contract,</li>
+  <li>consume the <code>.frog</code> front-panel instances,</li>
+  <li>resolve the <code>.wfrog</code> realization package and numeric SVG realization asset,</li>
+  <li>consume the native-kernel manifest where the LLVM-oriented proof path is used,</li>
+  <li>bind <code>ctrl_input.value</code> to the execution input,</li>
+  <li>execute the bounded accumulator kernel through the declared call boundary where applicable,</li>
+  <li>publish the result to the public output and to <code>ind_result.value</code>,</li>
+  <li>emit the runtime snapshot and diagnostic evidence.</li>
+</ul>
+
+<p>
+In a hosted Run/Execute loop, the host samples the input-side widget value, the runtime executes the bounded dataflow unit, and the result is projected back into the output-side widget and published snapshot.
+</p>
+
+<hr/>
+
+<h2>Boundary</h2>
+
+<ul>
+  <li><code>.frog</code> remains the canonical program source.</li>
+  <li><code>.wfrog</code> remains the widget/front-panel package and realization publication path.</li>
+  <li>SVG remains a visual realization resource.</li>
+  <li>FIR remains the open execution-facing representation derived from validated meaning.</li>
+  <li>Lowering and backend contracts remain the explicit downstream handoff.</li>
+  <li>LLVM remains one compiler-family native proof path.</li>
+  <li>The runtime remains a consumer and orchestrator of explicit contracts and artifacts.</li>
+  <li>The host UI remains replaceable and does not define FROG semantics.</li>
+</ul>

Expression/Widget package hosting.md

@@ -0,0 +1,71 @@
+<p align="center">
+  <img src="../FROG logo.svg" alt="FROG logo" width="140" />
+</p>
+
+<h1 align="center">Widget Package Hosting Role</h1>
+
+<p align="center">
+  <strong>How <code>.wfrog</code> packages participate in hosted front-panel realization</strong><br/>
+  <em>FROG — Free Open Graphical Language</em>
+</p>
+
+<hr/>
+
+<h2>Purpose</h2>
+
+<p>
+This companion note clarifies how widget packages participate when a FROG front panel is hosted by a runtime or UI host.
+It complements <a href="./Widget%20package%20%28.wfrog%29.md">FROG Widget Package (.wfrog)</a>.
+</p>
+
+<hr/>
+
+<h2>Boundary</h2>
+
+<ul>
+  <li><code>.frog</code> is the canonical program source.</li>
+  <li><code>.wfrog</code> publishes widget package and realization-facing metadata.</li>
+  <li>SVG and related assets are visual realization resources.</li>
+  <li>A runtime or host consumes compatible package information to realize and bind widgets.</li>
+</ul>
+
+<p>
+A <code>.frog</code> source may identify widget classes, widget package identities, or realization choices. A host may then resolve compatible <code>.wfrog</code> packages and related assets when a front panel needs to be rendered or interacted with.
+</p>
+
+<hr/>
+
+<h2>Hosting Flow</h2>
+
+<pre><code>.frog front_panel
+  -&gt; widget instances, layout, initial values, and diagram/widget bindings
+  -&gt; referenced widget classes or package identities
+  -&gt; compatible .wfrog package
+  -&gt; SVG/assets or other realization resources
+  -&gt; host UI
+  -&gt; runtime widget bindings</code></pre>
+
+<p>
+The host/runtime consumption role may include package resolution, asset loading, part mapping, value binding, property binding, event routing, capability checks, and diagnostic reporting.
+</p>
+
+<hr/>
+
+<h2>Non-Ownership Rules</h2>
+
+<ul>
+  <li>A <code>.wfrog</code> package does not replace the canonical <code>.frog</code> program source.</li>
+  <li>SVG assets do not define widget semantics.</li>
+  <li>A host-specific rendering path does not become portable widget law.</li>
+  <li>Runtime support claims remain separate from package validity.</li>
+  <li>Public widget law remains published through the widget/package specification surfaces.</li>
+</ul>
+
+<hr/>
+
+<h2>Practical Reading</h2>
+
+<p>
+In a hosted example, the front-panel branch and execution branch meet through runtime bindings.
+The <code>.wfrog</code> package helps the host realize visible widgets, while FIR, lowering, backend contracts, manifests, and runtime-family artifacts carry the execution-facing path.
+</p>

IR/Hybrid UI compiler execution.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <img src="../FROG logo.svg" alt="FROG logo" width="140" />
+</p>
+
+<h1 align="center">FIR in Hybrid UI and Compiler Execution</h1>
+
+<p align="center">
+  <strong>Clarifying the role of FIR when front-panel widgets, runtime orchestration, and compiler-family artifacts meet</strong><br/>
+  <em>FROG — Free Open Graphical Language</em>
+</p>
+
+<hr/>
+
+<h2>Purpose</h2>
+
+<p>
+This companion note clarifies how FIR participates in a practical FROG execution corridor that includes a front panel, widget bindings, runtime orchestration, and optional compiler-family artifacts such as LLVM-oriented native proof material.
+</p>
+
+<p>
+It complements <a href="./Readme.md">IR/Readme.md</a>, <a href="./Lowering.md">IR/Lowering.md</a>, and <a href="./Backend%20contract.md">IR/Backend contract.md</a> without replacing their ownership.
+</p>
+
+<hr/>
+
+<h2>Core Rule</h2>
+
+<p>
+FIR is the open execution-facing representation derived from validated program meaning. It is not authored directly, and it is not a runtime-private graph, compiler-private graph, LLVM IR file, widget package, visual asset, or host UI object table.
+</p>
+
+<pre><code>canonical .frog source
+  -&gt; loadability
+  -&gt; structural validation
+  -&gt; semantic validation
+  -&gt; validated program meaning
+  -&gt; FIR / Execution IR
+  -&gt; lowering
+  -&gt; backend contract
+  -&gt; runtime-family and/or compiler-family consumption</code></pre>
+
+<hr/>
+
+<h2>What FIR May Preserve</h2>
+
+<p>
+In hybrid UI/compiler execution, FIR may preserve execution-relevant consequences of validated widget and interface meaning, including:
+</p>
+
+<ul>
+  <li>public input and output participation,</li>
+  <li>validated diagram units and dataflow dependencies,</li>
+  <li>validated types and execution-facing units,</li>
+  <li>stable source attribution and recoverable source mapping,</li>
+  <li>widget identities where execution-facing interaction needs them,</li>
+  <li><code>widget_value</code> participation where a widget's primary value enters or receives execution data,</li>
+  <li><code>widget_reference</code> participation where object-style interaction targets properties, methods, events, or parts,</li>
+  <li>execution-relevant consequences of <code>frog.ui.property_read</code>, <code>frog.ui.property_write</code>, or <code>frog.ui.method_invoke</code>.</li>
+</ul>
+
+<p>
+This preservation exists so later lowering, backend contracts, runtime binding, diagnostics, probes, watches, and source-aligned observability can remain traceable.
+</p>
+
+<hr/>
+
+<h2>What FIR Must Not Absorb</h2>
+
+<p>
+FIR must not absorb or redefine ownership of:
+</p>
+
+<ul>
+  <li>canonical <code>.frog</code> source structure,</li>
+  <li><code>.wfrog</code> package definition,</li>
+  <li>SVG rendering strategy,</li>
+  <li>host-specific widget storage,</li>
+  <li>runtime-private scheduler state,</li>
+  <li>runtime-private UI object tables,</li>
+  <li>LLVM IR or compiler-private optimization state,</li>
+  <li>one host's rendering pipeline as if it were canonical open execution representation.</li>
+</ul>
+
+<hr/>
+
+<h2>Hybrid Execution Reading</h2>
+
+<p>
+A practical hosted execution may contain two branches:
+</p>
+
+<pre><code>diagram/computation branch:
+.frog diagram
+  -&gt; semantic validation
+  -&gt; FIR
+  -&gt; lowering
+  -&gt; backend contract
+  -&gt; LLVM-oriented artifact or other backend-family artifact where applicable
+
+front-panel/widget branch:
+.frog front_panel
+  -&gt; widget instances and bindings
+  -&gt; .wfrog packages or realization packages
+  -&gt; SVG/assets or other realization resources
+  -&gt; host UI</code></pre>
+
+<p>
+FIR sits on the execution-facing branch after validated meaning. It may carry enough widget-related identity and mapping to allow the runtime to bind values and object-style accesses, but it does not own the front-panel realization itself.
+</p>
+
+<hr/>
+
+<h2>Runtime and Compiler Boundary</h2>
+
+<p>
+A runtime may consume FIR-derived contracts, manifests, and artifacts. A compiler-family path such as LLVM may consume lowered material to produce a native proof or loadable artifact. Neither the runtime nor LLVM becomes the language owner.
+</p>
+
+<table>
+  <thead>
+    <tr>
+      <th>Layer</th>
+      <th>Correct role</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>FIR</td>
+      <td>Open execution-facing representation derived from validated meaning.</td>
+    </tr>
+    <tr>
+      <td>Lowering</td>
+      <td>Specialization toward target, backend, runtime, provider, or deployment concerns.</td>
+    </tr>
+    <tr>
+      <td>Backend contract</td>
+      <td>Explicit handoff to downstream consumers.</td>
+    </tr>
+    <tr>
+      <td>LLVM</td>
+      <td>One possible compiler-family consumer and native proof path.</td>
+    </tr>
+    <tr>
+      <td>Runtime</td>
+      <td>Execution and orchestration consumer of explicit contracts and artifacts.</td>
+    </tr>
+    <tr>
+      <td>Host UI</td>
+      <td>Rendering and interaction surface, replaceable by host family.</td>
+    </tr>
+  </tbody>
+</table>
+
+<hr/>
+
+<h2>Boundary Summary</h2>
+
+<ul>
+  <li>FIR is not <code>.frog</code>.</li>
+  <li>FIR is not <code>.wfrog</code>.</li>
+  <li>FIR is not SVG.</li>
+  <li>FIR is not LLVM IR.</li>
+  <li>FIR is not a runtime-private graph.</li>
+  <li>FIR may preserve execution-relevant widget consequences.</li>
+  <li>FIR must preserve source attribution where downstream execution, diagnostics, or observability need it.</li>
+</ul>