Skip to content

Readme.md

Latest commit

 

History

History
424 lines (324 loc) · 12.2 KB

Readme.md

File metadata and controls

424 lines (324 loc) · 12.2 KB

FROG logo

🐸 Reference Validator

Validation stage for the non-normative FROG reference implementation
FROG — Free Open Graphical Language

Contents

1. Overview

This directory contains validator logic for the non-normative FROG reference implementation. Its role is to determine, for the supported reference slice, whether loaded canonical source may proceed from source acceptance toward validated program meaning and then toward downstream derivation.

This validator is an implementation-side consumer of published repository law. It is not the owner of that law.

Accordingly, this directory exists to apply published validation boundaries, not to redefine them.

2. Why This Directory Exists

The reference implementation needs an explicit validation stage between loading canonical source and producing any downstream derived form.

Without that stage, an implementation could too easily collapse: 

loadable source
    !=
structurally valid canonical source

structurally valid canonical source
    !=
validated meaning

validated meaning
    !=
derived execution-facing form

The reference validator exists to keep those stages explicit in the implementation workspace.

It also helps ensure that the reference path remains inspectable, reproducible, and aligned with the published repository structure.

3. Non-Normative Status

This validator is part of Implementations/Reference/. It is therefore non-normative.

That means:

  • it does not define the language,
  • it does not define source-schema ownership,
  • it does not define semantic truth,
  • it does not define Execution IR,
  • it does not define backend contracts,
  • it does not define runtime-private realization.

If validator behavior and the published specification disagree, the specification wins. If the disagreement reveals ambiguity, the fix belongs in the relevant specification owner, not in private implementation folklore.

4. What This Directory Consumes

This directory consumes the published repository boundaries, including:

  • Expression/ for canonical source structure, structural validity, and source-schema posture,
  • Language/ for validated program meaning,
  • Libraries/ for intrinsic primitive identity and primitive-local requirements,
  • Profiles/ where optional standardized capability families affect legality,
  • Conformance/ for public accept / reject / preserve expectations relevant to the supported slice.

A machine-checkable schema artifact MAY assist the structural part of validation. However, such an artifact remains downstream from the published specification and upstream from semantic validation.

The validator therefore consumes published law in staged form. It does not invent a replacement source of truth.

5. Validation Staging

The reference validator should preserve the staged corridor explicitly: 

.frog source
    -> loadability
    -> source-shape / structural validation
    -> semantic validation
    -> candidate for downstream derivation

These stages must not be collapsed.

5.1 Loadability

This stage answers whether the source can be loaded as canonical JSON-based input at all. A failure here is not yet a structural-validity decision.

5.2 Source-shape / structural validation

This stage answers whether the loaded source satisfies the published structural rules of canonical FROG source for the relevant slice.

This includes top-level source shape, required versus optional section presence where relevant, and structurally required source objects for the supported slice.

A machine-checkable schema artifact may cover part of this stage. The validator may also contain additional structural checks where the published source contract requires them and a minimal declarative schema artifact is not sufficient on its own.

5.3 Semantic validation

This stage answers whether meaning is established for the supported slice after structural acceptance has already succeeded.

Typical semantic decisions include primitive legality, role legality, cycle legality, state legality, and other meaning-bearing rules that do not belong purely to source shape.

5.4 Candidate for downstream derivation

Only after structural and semantic validation have succeeded may the reference pipeline treat the program as a legitimate candidate for downstream Execution IR derivation or equivalent downstream reference processing.

6. Scope of the Current Reference Slice

The current reference validator should concentrate on the MVP slice exercised by the initial published examples and relevant conformance cases.

That slice includes, as applicable:

  • public interface participation,
  • ordinary core primitives,
  • widget_value,
  • widget_reference,
  • standardized UI primitives,
  • explicit local memory through frog.core.delay,
  • basic cycle legality,
  • clear rejection of role confusion and structurally or semantically invalid participation.

The validator should remain narrow enough that acceptance and rejection can be explained clearly for the supported slice.

7. What This Directory Owns

This directory owns implementation-side validation behavior for the supported reference slice, including:

  • implementation-side checking of published validation rules,
  • staged validation flow inside the reference implementation,
  • explicit acceptance or rejection of source cases for the supported slice,
  • source-aligned diagnostics,
  • enough source attribution to support downstream traceability if validation succeeds.

It may also own internal decomposition such as:

  • loadability checks,
  • structural checks,
  • semantic checks,
  • diagnostic classification.

8. What This Directory Does Not Own

This directory does not own:

  • the normative validation rules themselves,
  • the canonical definition of source schema,
  • language-semantics ownership,
  • primitive-catalog ownership,
  • Execution IR design ownership,
  • lowering ownership,
  • backend-contract ownership,
  • runtime-private scheduling truth.

It must not silently shift ownership from the published repository into implementation code.

In particular, this validator must not:

  • turn one machine-checkable schema artifact into the full definition of the language,
  • treat private implementation repair as public structural acceptance,
  • treat an implementation subset limitation as if the published specification had rejected the source,
  • treat successful execution as proof that the source was valid.

9. Diagnostic Posture

Diagnostics should preserve the stage at which failure occurred.

At minimum, the reference validator SHOULD distinguish:

  • loadability failure,
  • structural validation failure,
  • semantic validation failure,
  • supported-by-specification but not yet supported-by-reference-slice situations where applicable.

This distinction matters because: 

"not loadable"
    !=
"structurally invalid"

"structurally invalid"
    !=
"semantically invalid"

"not yet supported by this reference slice"
    !=
"rejected by the language"

Diagnostics should remain source-aligned and should preserve enough attribution to explain which source-side construct caused acceptance or rejection.

10. Design Rules

  • Reject invalid source explicitly.
  • Do not silently reinterpret invalid source.
  • Do not silently repair invalid source into a private acceptable form.
  • Keep structural validation distinct from semantic validation.
  • Preserve enough source identity for later attribution.
  • Keep the supported slice narrow and coherent.
  • Keep downstream derivation unavailable until validation has succeeded.
  • Keep implementation convenience downstream from published repository law.

11. Relation with Conformance

This validator is not the conformance surface. It is one implementation attempting to align with that surface. 

Specification defines
Conformance exposes
Reference validator consumes and applies

Accordingly:

  • published conformance cases define public expectations,
  • the reference validator should classify those cases correctly for the supported slice,
  • passing a case demonstrates alignment, not ownership.

If a conformance case cannot be classified clearly, that usually indicates one of three problems:

  • the validator is incomplete,
  • the supported reference slice is too vague,
  • the owning specification document needs clarification.

12. Relation with Derivation and Runtime

The validator is upstream from derivation and downstream from loading. 

Loader
   -> Validator
   -> Deriver
   -> Lowerer
   -> ContractEmitter
   -> Runtime-side consumption

The validator does not own the shape of the derived execution-facing representation. It only decides whether the source is an acceptable candidate to reach that stage for the supported slice.

Likewise, the validator does not own runtime realization. It must not let runtime-private behavior redefine validation truth.

13. Summary

The reference validator is the stage that classifies loaded canonical source for the non-normative reference implementation.

Its job is to preserve the staged corridor: 

loadability
   -> structural validation
   -> semantic validation
   -> candidate for downstream derivation

Without successful validation, the reference implementation must not claim that a case is a legitimate candidate for derived execution-facing form.

Core rule: 

published law first
reference validation second
downstream derivation only after acceptance