Skip to content

Express.md

Latest commit

 

History

History
865 lines (671 loc) · 28.9 KB

Express.md

File metadata and controls

865 lines (671 loc) · 28.9 KB

FROG logo

🐸 FROG IDE Express Specification

Definition of guided Express authoring entries for the FROG IDE
FROG — Free Open Graphical Language

Contents

1. Overview

Express authoring is an IDE-layer guided authoring capability that allows a user to insert, configure, and re-edit common programming tasks through a guided experience rather than through raw low-level assembly alone.

Its purpose is to improve usability, discoverability, speed of insertion, and correctness for recurring workflows while preserving the canonical FROG model.

Express is therefore a guided authoring presentation mechanism, not a separate language. A conforming FROG IDE MAY expose Express entries, but any inserted Express-authored content MUST normalize to canonical FROG content already valid in the active canonical insertable space of the IDE.

This document defines the normative IDE-facing role of Express entries, their lifecycle, their configuration model, their relationship to canonical source, and the minimum rules required to preserve stable round-trip authoring. 

One-line model

guided entry
    -> canonical target
    -> canonical content
    -> execution-facing systems

Never:

guided entry
    -> hidden semantic construct

2. Scope for v0.1

For FROG v0.1, this document standardizes:

  • what an Express entry is,
  • what Express is not,
  • the IDE-facing lifecycle of Express-authored instances,
  • the distinction between configurable parameters and expandable terminals,
  • the requirement that Express normalize to canonical content,
  • the use of optional non-authoritative recoverability metadata for re-editability.

This document does not standardize:

  • a new canonical node kind,
  • a new semantic structure family,
  • new primitive semantics,
  • new profile semantics,
  • a mandatory UI style for guided editing,
  • a requirement that every canonical entry must provide an Express surface,
  • a requirement that runtimes understand or consume Express-private state.

3. Architectural Position and Dependencies

3.1 Repository position

This document belongs in IDE/ because it defines a guided authoring behavior of the IDE. It does not belong to Expression/, Language/, Libraries/, or Profiles/ because it does not own canonical source identity, execution meaning, primitive-local semantics, or profile-owned capability semantics.

3.2 Dependencies

This document depends on the following specifications:

  • IDE/Readme.md — architectural role of Express authoring in the IDE layer,
  • IDE/Palette.md — discovery, search, filtering, insertion, and the rule that all insertion paths resolve to the same canonical insertable space,
  • IDE/Snippet.md — insertion and fragment-handling behavior for authoring fragments,
  • Expression/Readme.md — canonical source ownership and the optional source-level ide section,
  • Expression/IDE preferences.md — non-authoritative IDE-facing recoverability metadata,
  • Expression/Diagram.md — canonical graph objects and standard node kinds,
  • Expression/Control structures.md — canonical structure identities and the rule that authoring-facing derived forms do not create new canonical structure families,
  • Libraries/ documents — intrinsic primitive identities and primitive-local semantics,
  • Profiles/ documents — optional standardized capability families and profile-owned capability meaning,
  • Language/ documents — cross-cutting normative execution semantics.

3.3 Ownership boundary

If a conflict appears, the following ownership rules apply:

  • Expression/ remains authoritative for canonical source representation,
  • Language/ remains authoritative for normative execution meaning,
  • Libraries/ remain authoritative for intrinsic primitive identity and primitive-local semantics,
  • Profiles/ remain authoritative for optional standardized capability families and profile-owned meaning,
  • IDE/Express.md remains authoritative only for guided authoring behavior.
Ownership reminder

Expression/   -> canonical source representation
Language/     -> normative execution meaning
Libraries/    -> intrinsic primitive identity and local semantics
Profiles/     -> optional standardized capability families
IDE/Express   -> guided authoring behavior

If a conflict arises between Express presentation and canonical ownership, canonical ownership wins.

4. Design Principles

4.1 Faster authoring without semantic drift

Common tasks SHOULD be insertable with less friction than manual low-level assembly. That convenience MUST NOT create hidden language semantics.

4.2 Same canonical insertable space

Express authoring MUST resolve to the same canonical insertable space as other insertion paths. An Express lens is a guided access mode over canonical content, not an alternative semantic universe.

4.3 Preserved canonical identity

An Express-authored instance MUST resolve to a canonical target whose identity remains knowable. The user SHOULD be able to discover what canonical primitive, sub-FROG, or canonical fragment the guided entry actually targets.

4.4 Stable re-editability

An Express-authored instance SHOULD remain safely reconfigurable after load and reload when the IDE preserves sufficient non-authoritative recoverability state.

4.5 Tooling independence from Express-private state

Validation, execution preparation, debugging, probes, watches, snippets, and execution-facing systems MUST remain grounded in canonical content rather than in Express-private UI state.

4.6 Transparency

The IDE SHOULD make it possible to inspect:

  • the Express entry identity,
  • the canonical target identity,
  • the current configuration mapping,
  • the visible optional terminals if relevant.

4.7 Minimal but extensible

FROG v0.1 defines a conservative Express model. Stronger IDE implementations MAY provide richer guided experiences, provided that canonical normalization, canonical ownership, and execution-facing independence remain preserved.

5. What an Express Entry Is

An Express entry is an IDE-defined, guided, task-oriented authoring entry that inserts or edits canonical FROG content through a guided configuration workflow.

An Express entry is characterized by the following properties:

  • it is guided,
  • it is instance-local,
  • it is task-oriented,
  • it is normalizable to canonical content,
  • it is re-editable when sufficient non-authoritative recoverability state is preserved.

An Express entry MAY represent:

  • a guided configuration surface for a single canonical primitive node,
  • a guided configuration surface for a canonical subfrog node,
  • a guided materialization process for a deterministic canonical fragment.

A conforming IDE SHOULD make the canonical target identity visible somewhere in the guided experience, entry metadata, or instance detail view.

6. What Express Is Not

Express is not:

  • a new canonical node kind,
  • a new semantic structure family,
  • a replacement for canonical source identity,
  • a reason for execution-facing systems to depend on editor-private UI state,
  • a permission to hide semantically required program content from conforming tooling.

Accordingly:

  • an Express entry MUST NOT redefine primitive identity,
  • an Express entry MUST NOT redefine profile-owned capability identity,
  • an Express entry MUST NOT redefine language semantics,
  • an Express entry MUST NOT require a conforming runtime to understand IDE-private Express state,
  • an Express entry MUST NOT make canonical execution meaning ambiguous.

7. Express Kinds

A conforming IDE MAY support one or more of the following Express kinds.

7.1 Primitive-backed Express

A primitive-backed Express entry configures one canonical primitive node. This is the most direct Express form and is appropriate when:

  • the canonical primitive already exists,
  • the primitive has meaningful configurable parameters,
  • optional terminals may need to be exposed progressively,
  • the guided experience mainly improves usability rather than structural composition.

7.2 Sub-FROG-backed Express

A sub-FROG-backed Express entry configures one canonical subfrog node. This form is appropriate when:

  • the guided task is better represented as a reusable program unit,
  • the underlying behavior is more complex than a single primitive,
  • the IDE should expose a task-oriented entry while preserving a clean canonical diagram identity.

A sub-FROG-backed Express entry MUST preserve the canonical subfrog identity and MUST NOT invent a boundary different from the one implied by the referenced FROG interface.

7.3 Fragment-backed Express

A fragment-backed Express entry deterministically materializes a canonical fragment containing multiple canonical objects. This form SHOULD be used more conservatively because it requires stronger guarantees for:

  • stable re-editability,
  • deterministic materialization,
  • mapping from Express instance state to owned canonical objects,
  • safe detach or materialize behavior.

For v0.1, primitive-backed and sub-FROG-backed Express are the preferred baseline. Fragment-backed Express MAY exist, but it SHOULD remain conservative and predictable. 

Preferred baseline for v0.1

primitive-backed   -> preferred
subfrog-backed     -> preferred
fragment-backed    -> allowed, but conservative

8. Configuration Model

An Express entry SHOULD provide a guided configuration experience appropriate to the target task. That experience MAY be implemented through:

  • a modal dialog,
  • a non-modal properties panel,
  • an inline popover,
  • a staged wizard,
  • another equivalent IDE interaction surface.

The configuration experience SHOULD allow the user to:

  • understand what the entry does,
  • set configuration values,
  • review visible optional terminals,
  • preview the canonical target identity,
  • confirm insertion,
  • reopen the same configuration later when re-editing.

A conforming IDE MAY provide task-oriented wording and grouped controls that are more approachable than raw canonical parameter names, but the mapping from those controls to canonical content MUST remain deterministic.

9. Configurable Parameters vs Expandable Terminals

If Express authoring is supported, the IDE SHOULD distinguish clearly between:

  • configurable parameters — values or options primarily edited through the guided configuration experience,
  • expandable terminals — optional visible inputs or outputs that the user may choose to expose directly on the diagram,
  • canonical target identity — the actual primitive, sub-FROG, or canonical fragment to which the Express instance resolves.

9.1 Configurable parameters

Configurable parameters typically represent:

  • modes,
  • units,
  • defaults,
  • policy selections,
  • constant values,
  • other options best edited through a guided form.

A configurable parameter MAY map to:

  • a canonical constant input value,
  • a configuration field for a sub-FROG-backed instance,
  • a deterministic materialization choice for a fragment-backed instance.

9.2 Expandable terminals

Expandable terminals are optional visible terminals that the user may expose or hide for authoring convenience. The following rules apply:

  • an expandable terminal MUST correspond to a port valid for the canonical target,
  • an Express presentation MUST NOT invent semantically invalid terminals,
  • an Express presentation MUST NOT hide a semantically required terminal in a way that makes the canonical model ambiguous,
  • the mapping between configuration state and terminal visibility SHOULD be deterministic.

10. Canonical Normalization

Canonical normalization is the process by which an Express presentation becomes ordinary canonical FROG content.

A conforming IDE MUST ensure that:

  • an Express entry normalizes to content already valid in the active canonical insertable space,
  • normalization preserves the intended source-level meaning,
  • execution-facing systems can operate on normalized canonical content without depending on Express UI state.

Canonical normalization MAY target:

  • a canonical primitive node,
  • a canonical subfrog node,
  • a deterministic canonical fragment whose owned objects are all valid under the active insertable space.

The normalization process MUST NOT:

  • create a hidden semantic family,
  • introduce runtime-required editor-private data,
  • change canonical meaning depending on transient editor UI state alone.
Normalization rule

guided presentation
    -> canonical target
    -> canonical content

Execution-facing systems consume:
- canonicalized content

They do not consume:
- guided UI state

If an Express workflow materializes canonical content through guided user choices, deterministic generation, or AI participation, a provenance-aware IDE SHOULD classify that authoring path explicitly. Direct human configuration, tool generation, and AI-assisted generation SHOULD NOT be collapsed into the same provenance claim merely because all of them normalize to valid canonical content. 

Express provenance posture

guided human configuration  -> human_guided or equivalent claim
deterministic materializer   -> tool_generated or equivalent claim
AI-assisted materializer     -> ai_assisted / ai_generated claim

all cases still normalize to canonical FROG content

11. Instance Model

Each Express-authored instance SHOULD have a stable IDE-level identity while the user edits the program.

A conforming IDE SHOULD be able to associate the following conceptual elements with an Express-authored instance:

  • instance identity — the IDE-side identity of the Express-authored occurrence,
  • express identity — the Express entry definition used to create or edit the instance,
  • canonical target identity — the primitive, sub-FROG, or fragment target to which the instance resolves,
  • configuration state — non-authoritative recoverability state sufficient to reopen guided editing,
  • visible optional terminals — the current authoring-facing terminal exposure state,
  • owned canonical objects — the canonical object or objects created or edited by the instance.

This instance model is an IDE concern. It MUST remain reducible to canonical content for execution-facing purposes.

12. Palette Integration

Express entries integrate with the palette as guided insertion entries. They MAY appear in:

  • primary intent-first browsing,
  • search results,
  • context-aware insertion results,
  • a dedicated guided or Express lens.

A conforming IDE SHOULD:

  • make Express entries visually distinguishable from direct primitive, structure, node-insertion, and annotation entries,
  • disclose canonical target identity in entry metadata or detail view,
  • allow the user to reach the corresponding direct canonical entry where that improves transparency.

Express entries MUST remain semantically consistent with the same underlying canonical insertable space as other insertion paths. An Express lens is therefore a convenience surface, not a distinct semantic catalog.

Express entries SHOULD be especially useful for task-oriented workflows such as:

  • common I/O tasks,
  • common signal-processing tasks,
  • common connectivity tasks when relevant profile support is active,
  • other repetitive workflows where guided configuration materially improves usability.

Express entries MAY also exist for implementation-supported third-party surfaces. When they do, the IDE SHOULD keep them visually distinguishable from baseline standardized entries and from standardized profile-defined entries.

13. Edit, Reopen, Detach, and Materialize

A conforming IDE SHOULD support the following lifecycle operations for Express-authored instances where Express is available:

  • insert and configure — create the initial canonical target through a guided workflow,
  • reopen configuration — reopen guided editing for a previously inserted instance,
  • reconfigure — change configuration and update canonical content deterministically,
  • detach or discard Express presentation — remove the guided layer while preserving valid canonical content,
  • materialize — when supported, convert the guided instance into plain canonical content with no remaining guided editing contract.

13.1 Reopen

Reopening configuration SHOULD restore enough guided state to allow meaningful continued editing without reconstructing the instance from guesswork alone.

13.2 Detach

Detach removes the Express presentation while leaving the underlying canonical object model intact. After detach:

  • the resulting content MUST remain valid canonical FROG content,
  • execution-facing behavior MUST remain grounded in canonical meaning,
  • the user MAY continue editing the resulting content directly.

13.3 Materialize

Materialize is especially relevant for fragment-backed Express. When materialization is supported:

  • the resulting canonical fragment MUST be deterministic,
  • the IDE SHOULD make clear that future reconfiguration may no longer use the original guided contract,
  • materialization MUST NOT produce semantically hidden required content.
Lifecycle model

insert
   -> configure
   -> normalize to canonical target
   -> reopen / reconfigure if supported
   -> detach safely if desired
   -> materialize if supported

14. Program Model and Optional Source Persistence

14.1 Program Model representation

The FROG Program Model MAY preserve non-authoritative Express-related state in memory during editing. That state SHOULD be sufficient to support:

  • stable mapping from an Express instance to owned canonical objects,
  • reopen and reconfigure workflows,
  • deterministic terminal visibility,
  • safe detach or materialize operations,
  • round-trip editing without semantic drift.

Typical IDE-side Program Model concerns include:

  • preferred guided presentation,
  • configuration state,
  • per-instance editor hints,
  • optional terminal visibility state,
  • mapping to canonical target identity.

This state remains IDE-owned and non-authoritative for execution semantics.

14.2 Optional source persistence

The FROG source format MAY optionally persist IDE-facing recoverability aids through the source-level ide section owned by the Expression layer. Within that section, Express-related data SHOULD be treated as recoverability metadata rather than as executable program content.

If Express-related state is persisted there:

  • it MUST remain optional,
  • it MUST remain non-authoritative for execution semantics,
  • it MUST NOT be required to determine canonical executable meaning,
  • it SHOULD support stable reopen and re-edit workflows,
  • it MUST be safely ignorable by runtimes, compilers, and other execution-facing systems.

Examples of persistable Express-related IDE state MAY include:

  • Express entry identity,
  • guided presentation preferences,
  • recoverable configuration values,
  • optional terminal visibility state,
  • mapping from Express instance identity to owned canonical objects.

A conforming runtime MUST NOT require this state in order to execute the program. 

Source persistence rule

canonical source
    may carry
optional recoverability metadata

Recoverability metadata
    -> helps IDE reopen guided state
    -> does not define execution meaning

15. Validation Rules

A conforming IDE MUST validate Express behavior against canonical ownership and canonical validity. At minimum:

  • an Express entry MUST resolve to valid canonical content,
  • the disclosed canonical target identity MUST match the actual normalized target,
  • expandable terminals MUST correspond to ports valid for the canonical target,
  • reconfiguration MUST update canonical content deterministically,
  • detach or materialize MUST leave valid canonical content,
  • execution-facing systems MUST be able to ignore Express-private presentation state.

A conforming IDE SHOULD also detect and report:

  • broken mappings between Express instances and canonical targets,
  • configuration states that no longer match the active insertable space,
  • profile mismatches that would make a profile-defined target unavailable or invalid,
  • third-party extension mismatches where the referenced target surface is unavailable,
  • stale recoverability state that cannot safely be reapplied.

16. Examples

16.1 Primitive-backed Express example

A guided numeric filter entry MAY configure one canonical primitive target. The guided UI may expose:

  • filter family,
  • cutoff value,
  • units,
  • optional error terminals.

After insertion, the canonical target remains an ordinary canonical object known to the active insertable space.

16.2 Sub-FROG-backed Express example

A task-oriented file-reading entry such as Read Text File MAY configure one canonical subfrog node whose public contract is easier to present through guided wording than through raw low-level assembly.

16.3 Fragment-backed Express example

A guided acquisition or connectivity workflow MAY materialize a deterministic fragment containing several canonical objects. If so, the IDE MUST preserve deterministic mapping between the Express instance and that fragment for as long as guided re-editing is supported.

16.4 Conceptual persisted IDE metadata example

{
  "ide": {
    "recoverability": {
      "express_bindings": [
        {
          "instance_id": "expr_001",
          "express_id": "frog.ide.express.read_text_file",
          "canonical_target_kind": "subfrog",
          "canonical_target_ref": "frog.io.read_text_file.basic",
          "visible_optional_terminals": ["error_in", "error_out"],
          "config": {
            "encoding": "utf8",
            "line_endings": "auto"
          }
        }
      ]
    }
  }
}

This example is conceptual. It illustrates the kind of non-authoritative recoverability state an IDE MAY preserve. It does not redefine canonical execution meaning.

17. Out of Scope for v0.1

  • turning Express into a new canonical node kind,
  • turning Express into a new canonical structure family,
  • requiring runtimes to interpret Express-private presentation state,
  • opaque Express systems whose canonical target cannot be determined by a conforming IDE,
  • automatic hidden semantic transformation beyond deterministic canonical normalization,
  • marketplace-specific Express UX or commercial distribution workflows,
  • cloud-hosted Express catalogs,
  • a requirement that every primitive family already provide Express entries,
  • full standardization of fragment-backed Express lifecycle semantics across all future profiles,
  • execution-private helper content that cannot be represented as canonical FROG content.

18. Summary

Express authoring gives the FROG IDE a guided insertion model for common tasks without creating a separate language.

  • Express entries belong to the IDE layer.
  • They MUST normalize to canonical FROG content.
  • They MUST NOT become new semantic node kinds or structure families.
  • They SHOULD disclose canonical target identity.
  • They MAY preserve non-authoritative recoverability state in the Program Model and, optionally, in the source-level ide section.
  • They SHOULD support insert, configure, reopen, reconfigure, and safe detach workflows.
  • Execution-facing systems MUST remain grounded in canonicalized content rather than guided UI state.

This gives FROG a modern guided-authoring model compatible with practical IDE workflows while preserving an open, durable, canonical graphical language representation.

19. License

This specification is part of the FROG repository and is governed by the repository license and contribution rules.