Skip to content

internal-artifacts.md

Latest commit

 

History

History
611 lines (487 loc) · 14.8 KB

internal-artifacts.md

File metadata and controls

611 lines (487 loc) · 14.8 KB

FROG logo

Reference Internal Artifacts

Internal artifact taxonomy used by the FROG reference implementation across load, validation, derivation, lowering, contract emission, and runtime execution
FROG — Free Open Graphical Language

Contents

1. Overview

This document defines the internal artifact taxonomy used by the reference implementation workspace.

Its purpose is to keep implementation stages explicit and to ensure that the following documents all talk about the same internal objects:

  • Readme.md,
  • pipeline.md,
  • frogc.md,
  • example-artifact-requirements.md.

This document does not standardize repository-wide normative syntax for every possible implementation artifact. It defines a coherent internal naming and boundary model for the reference implementation workspace.

2. Status and Boundary

All artifact kinds defined here are non-normative implementation artifacts. They do not replace:

  • canonical source,
  • structural validity,
  • validated semantic meaning,
  • canonical Execution IR,
  • lowering law,
  • backend contract law.

Instead, they are the reference implementation's working surfaces for consuming the published repository architecture in a recoverable way.

The key rule is: 

internal artifact
    !=
normative language layer

3. Design Goal

The internal artifact model should satisfy the following goals:

  • stage clarity — each artifact should correspond to a clear pipeline stage,
  • traceability — source attribution should remain recoverable,
  • subset honesty — unsupported-but-valid situations should remain explicit,
  • cross-document consistency — the same artifact names should appear coherently in CLI, pipeline, and example requirements,
  • bounded usefulness — the first priority slice should be fully representable through these artifacts.

4. Artifact Family Map

The intended internal artifact family map is: 

source file
    |
    v
frog_loaded_source
    |
    v
frog_validation_result
    |
    v
frog_derived_execution_ir
    |
    v
frog_lowered_form
    |
    v
frog_backend_contract
    |
    v
frog_runtime_result

Optional implementation-side helper artifacts MAY appear between those main stages, but they SHOULD map clearly to one of those families rather than inventing a competing pipeline vocabulary.

5. Artifact Kinds

The primary artifact kinds used by the reference implementation are:

  • frog_loaded_source,
  • frog_validation_result,
  • frog_derived_execution_ir,
  • frog_lowered_form,
  • frog_backend_contract,
  • frog_runtime_result.

Each artifact SHOULD carry:

  • artifact_kind,
  • artifact_version,
  • source_ref when meaningful,
  • program_id when meaningful,
  • stage_ref or equivalent stage identity when useful.

A useful common envelope pattern is: 

{
  "artifact_kind": "<kind>",
  "artifact_version": "0.1",
  "source_ref": {
    "path": "<path>"
  },
  "program_id": "<program_id>",
  "stage_ref": "<stage_name>"
}

6. Loader Artifacts

The loader stage SHOULD produce a frog_loaded_source artifact.

Its job is to record:

  • the source path,
  • the decoded top-level object,
  • the load status,
  • and any immediate decoding diagnostics.

Conceptual shape: 

{
  "artifact_kind": "frog_loaded_source",
  "artifact_version": "0.1",
  "source_ref": {
    "path": "Examples/05_bounded_ui_accumulator/main.frog"
  },
  "status": "ok",
  "decoded_source": {
    "<top_level_sections>": {}
  },
  "diagnostics": []
}

A failed load SHOULD still return a recoverable artifact surface when possible, but with:

  • status set to a load failure state,
  • and no claim that validation succeeded.

7. Validation Artifacts

The validation stage SHOULD produce a frog_validation_result artifact.

Its job is to distinguish at least:

  • load failure,
  • structural invalidity,
  • semantic rejection,
  • unsupported-but-valid status,
  • successful validation.

Conceptual shape: 

{
  "artifact_kind": "frog_validation_result",
  "artifact_version": "0.1",
  "source_ref": {
    "path": "Examples/05_bounded_ui_accumulator/main.frog"
  },
  "status": "ok",
  "validated_subset": {
    "widget_value": true,
    "widget_reference": true,
    "ui_object_primitives": true,
    "explicit_local_memory": true,
    "bounded_loop": true
  },
  "validated_program": {
    "program_id": "prog:05_bounded_ui_accumulator",
    "entry_kind": "single_frog_program"
  },
  "diagnostics": []
}

This artifact is the first one that must explicitly record subset posture. It is the correct place to say:

  • supported and accepted,
  • rejected,
  • or valid in the broader published model but unsupported by the current reference subset.

8. Execution IR Derivation Artifacts

The derivation stage SHOULD produce a frog_derived_execution_ir artifact.

Its job is to expose an attributable execution-facing representation derived from validated meaning.

Conceptual shape: 

{
  "artifact_kind": "frog_derived_execution_ir",
  "artifact_version": "0.1",
  "source_ref": {
    "path": "Examples/05_bounded_ui_accumulator/main.frog"
  },
  "program_id": "prog:05_bounded_ui_accumulator",
  "execution_unit": {
    "id": "unit:main",
    "objects": [],
    "connections": []
  },
  "diagnostics": []
}

This artifact SHOULD preserve at least:

  • execution-unit identity,
  • boundary objects,
  • primitive identity,
  • explicit state identity when present,
  • distinction between semantic and presentation-only surfaces.

9. Lowering Artifacts

The lowering stage SHOULD produce a frog_lowered_form artifact.

Its job is to specialize the open execution-facing representation for one selected backend family.

Conceptual shape: 

{
  "artifact_kind": "frog_lowered_form",
  "artifact_version": "0.1",
  "program_id": "prog:05_bounded_ui_accumulator",
  "backend_family": "reference_host_runtime_ui_binding",
  "assumptions": {},
  "units": [],
  "diagnostics": []
}

This artifact SHOULD make explicit:

  • selected backend family,
  • lowered units,
  • specialization assumptions,
  • any narrowed runtime expectations.

The lowered form remains downstream from canonical Execution IR. It is not a replacement for it.

10. Backend Contract Artifacts

The contract emission stage SHOULD produce a frog_backend_contract artifact.

Its job is to declare what the runtime or downstream backend-side consumer must accept and execute.

Conceptual shape: 

{
  "artifact_kind": "frog_backend_contract",
  "artifact_version": "0.1",
  "program_id": "prog:05_bounded_ui_accumulator",
  "backend_family": "reference_host_runtime_ui_binding",
  "assumptions": {},
  "units": [],
  "unsupported": [],
  "diagnostics": []
}

This artifact SHOULD make explicit:

  • unit identities,
  • state-cell obligations when present,
  • UI bindings when present,
  • public boundary obligations when present,
  • unsupported surfaces preserved only as non-semantic metadata.

11. Runtime Artifacts

The runtime stage SHOULD produce a frog_runtime_result artifact.

Its job is to record the outcome of runtime-side consumption of the backend contract.

Conceptual shape: 

{
  "artifact_kind": "frog_runtime_result",
  "artifact_version": "0.1",
  "program_id": "prog:05_bounded_ui_accumulator",
  "status": "ok",
  "contract_ref": {
    "unit_ids": ["main"]
  },
  "execution_summary": {},
  "outputs": {},
  "diagnostics": []
}

This artifact SHOULD distinguish:

  • runtime success,
  • explicit runtime rejection,
  • runtime failure after contract acceptance.

It SHOULD also preserve observable result surfaces separately, such as:

  • public outputs,
  • UI outputs,
  • UI effects,
  • explicit state surfaces.

12. UI Host Artifacts

For UI-bearing slices, the implementation MAY use additional internal UI-host-facing helper artifacts.

Examples include:

  • frog_ui_binding_plan,
  • frog_ui_host_state,
  • frog_ui_effect_log.

Such helper artifacts MAY be useful internally, especially for:

  • widget value reads and writes,
  • widget reference resolution,
  • property-write application,
  • UI effect reporting.

However:

  • they SHOULD map clearly to the main artifact family chain,
  • they MUST NOT become hidden substitutes for the main stage artifacts,
  • they MUST NOT be mistaken for normative specification layers.

13. Subset Honesty and Unsupported Status

Every stage that can encounter a broader published feature than the current reference subset supports SHOULD remain explicit about unsupported status.

A useful diagnostic distinction is:

  • rejected — invalid even in the published model being claimed against,
  • unsupported_but_valid — valid in the broader published model, but outside the current reference subset,
  • implementation_private_extension — available only as an explicit implementation-side extension.

This distinction is especially important when the repository architecture already permits richer future widget-class families than the subset actually exercised by the reference pipeline.

14. Example 05 Minimum Artifact Chain

For the first priority slice: 

Examples/05_bounded_ui_accumulator/main.frog

the minimum expected internal artifact chain is: 

frog_loaded_source
    -> frog_validation_result
    -> frog_derived_execution_ir
    -> frog_lowered_form
    -> frog_backend_contract
    -> frog_runtime_result

The minimum observable facts that this chain must preserve include:

  • the existence of the u16 control and indicator widgets,
  • the distinction between widget_value and widget_reference,
  • the bounded loop count of five,
  • the explicit state path through frog.core.delay,
  • the final public output,
  • the final indicator value,
  • the separate reporting of presentation-property writes such as face_color,
  • the non-semantic status of source-persisted face_template.

15. Stability Rule

The exact field spelling of these internal artifacts MAY evolve as the reference implementation grows.

However, the following SHOULD remain stable unless a documented reference-side migration is introduced:

  • the primary artifact-kind names,
  • their stage ordering,
  • their semantic intent,
  • their role in CLI output and artifact requirements.

This rule exists so that:

  • frogc.md,
  • pipeline.md,
  • example-artifact-requirements.md,
  • and implementation code

do not drift into competing internal vocabularies.

16. Summary

This document defines the reference implementation's internal artifact taxonomy.

Its purpose is to keep the workspace aligned on one stage-separated internal chain:

  • frog_loaded_source,
  • frog_validation_result,
  • frog_derived_execution_ir,
  • frog_lowered_form,
  • frog_backend_contract,
  • frog_runtime_result.

That alignment makes it possible for the reference implementation to remain explicit, traceable, and honest about what it really executes today, especially for the first priority bounded UI accumulator slice.