Skip to content

Readme.md

Latest commit

 

History

History
1117 lines (938 loc) · 48.7 KB

Readme.md

File metadata and controls

1117 lines (938 loc) · 48.7 KB

FROG logo

🐸 FROG Libraries

Intrinsic standardized primitive library specifications for FROG
FROG — Free Open Graphical Language

Contents

1. Overview

This directory contains the intrinsic standardized primitive library specifications used by FROG programs.

In FROG, executable diagrams may contain nodes of kind primitive. The meaning of such nodes is not fully determined by their serialized presence alone. Primitive identity and primitive-local contract must come from a stable normative source.

This directory is that normative home for the primitive vocabularies that belong to the intrinsic language surface.

In the current repository architecture:

  • Expression/ defines how primitive nodes appear in canonical source,
  • Language/ defines cross-cutting execution semantics for validated programs,
  • Libraries/ defines intrinsic standardized primitive vocabularies and primitive-local contracts,
  • Profiles/ defines optional standardized capability families beyond the intrinsic core,
  • IR/ defines the canonical execution-facing representation derived from validated meaning together with lowering and backend-facing boundaries,
  • IDE/ may expose primitives in palettes and authoring flows without redefining them.

The purpose of Libraries/ is therefore intentionally narrow: it standardizes primitive families that are fundamental, portable, and intrinsic to the FROG language surface itself.

FROG distinguishes the minimal core primitive set, lightweight standard library families, and optional external capability families. Lightweight standard libraries are part of the base FROG language distribution when published here, but they remain explicit diagram primitives rather than hidden runtime features. 

frog.core.*       -> foundational operators and execution building blocks
frog.image.*      -> lightweight standard library primitives
Profiles/ or
external packages -> optional or environment-specific capability families

For the widget corridor, this layer also becomes the normative home of the intrinsic executable interaction vocabulary, while widget instances, widget class law, widget behavior, widget realization, and widget-oriented packaging remain owned elsewhere.

2. Why this Layer Exists

A diagram can declare that a node is a primitive, but the diagram alone does not fully define what that primitive means. That meaning must come from a stable normative source.

For example: 

{
  "id": "add_1",
  "kind": "primitive",
  "type": "frog.core.add"
}

The diagram identifies the primitive node. It does not by itself define the full primitive contract. That contract comes from the relevant library specification together with the broader execution semantics defined elsewhere.

This layer exists so that intrinsic primitive identity remains:

  • explicit,
  • portable,
  • tool-independent,
  • stable across IDEs, validators, runtimes, compilers, and other implementations.

Without a dedicated library layer, primitive meaning would risk being scattered across:

  • diagram examples,
  • tooling behavior,
  • runtime conventions,
  • vendor-specific interpretations.

This directory prevents that drift by giving intrinsic primitive vocabularies a clear normative home.

That same discipline is now especially important for the widget corridor: the source-level widget interaction model cannot remain credible if the executable primitive surface is left to runtime-private convention.

3. Scope of this Directory

This directory specifies intrinsic library-level primitive catalogs. It defines which intrinsic standardized primitives exist, how they are named, what ports they expose, what primitive-local metadata they require, and what primitive-local behavior belongs to them.

This directory is the normative home for questions such as:

  • Which intrinsic primitive identifiers exist?
  • Which intrinsic namespace owns a primitive?
  • What ports does a primitive expose?
  • What primitive-local metadata is required?
  • What primitive-local behavior belongs to that primitive family?

This directory does not define:

  • the canonical .frog source structure,
  • the general executable graph model,
  • the general type-expression model,
  • the widget object model,
  • front-panel serialization,
  • cross-cutting execution semantics for validated programs,
  • the canonical Execution IR object model,
  • lowering strategy,
  • backend contract content,
  • IDE palette organization or authoring workflows,
  • optional profile-owned capability families,
  • implementation-specific extensions.

Those concerns are normatively owned elsewhere in the repository.

This directory also does not own the standardized primitive widget catalog itself. The primitive UI interaction surface belongs in Libraries/, while the standardized primitive widget families themselves belong in their own normative library-facing widget specifications rather than being smuggled into the executable primitive corridor.

4. Architectural Position

The position of Libraries/ inside the repository architecture is intentionally narrow and explicit: 

Repository architecture around Libraries/

Expression/   -> canonical source form
Language/     -> normative execution meaning
Libraries/    -> intrinsic primitive vocabularies
Profiles/     -> optional standardized capability families
IR/           -> canonical execution-facing representation and downstream boundaries
IDE/          -> authoring, palette, observability, debugging, inspection

Libraries/ own intrinsic primitive definitions referenced by executable diagrams.
Libraries/ do not own source structure, cross-cutting execution semantics,
optional capability profiles, IR derivation, lowering, backend contracts,
or IDE behavior.

This separation matters because the same primitive identity may be:

  • serialized in source by Expression/,
  • interpreted locally through Libraries/,
  • executed under broader constraints described by Language/,
  • represented later in execution-facing form by IR/,
  • lowered or packaged as part of an explicit standard-library dependency closure,
  • surfaced to users by IDE/Palette.md,
  • constrained by optional capability contracts defined in Profiles/.

This also explains why Libraries/Connectivity.md is retained only as a transition note: the authoritative normative home for frog.connectivity.* is now the Interop profile, not the intrinsic library core.

For the widget corridor, the same rule applies: 

Expression/
    owns widget interaction source representation

Libraries/
    own frog.ui.* primitive-local contract

Language/
    owns validated semantic meaning

IR/
    owns execution-facing derivation and downstream transformation

5. How a Primitive Gets its Meaning

The following diagram summarizes how an intrinsic primitive node is interpreted: 

Canonical source (.frog)
        |
        v
Expression/Diagram.md
declares a primitive node
        |
        v
"type": "frog.core.add"
        |
        v
Libraries/Core.md
defines the primitive-local contract
        |
        v
Language/
applies cross-cutting execution semantics
        |
        v
validated executable meaning
        |
        v
IR/
may derive canonical execution-facing representation

Primitive meaning is therefore composed, not collapsed into one document:

  • Expression/ owns representation,
  • Libraries/ own intrinsic primitive identity and primitive-local contract,
  • Language/ owns cross-cutting execution meaning,
  • IR/ owns derived execution-facing representation after validated meaning already exists.

For frog.ui.*, this composition also depends on the widget-side source model: 

Expression/Widget.md
         +
Expression/Widget interaction.md
         +
Expression/Widget class contract.md
         +
Libraries/UI.md
         +
Language/
         =
validated executable meaning of UI interaction

This is exactly why the widget corridor must remain layered: no one document and no one runtime should be allowed to absorb the full meaning alone.

6. Current Documents

This directory currently contains the following documents:

  • Readme.md — architectural entry point for intrinsic standardized primitive libraries.
  • Core.md — foundational frog.core primitives.
  • Math.md — standard frog.math scalar primitives plus the conservative public staging note for frog.numeric and future frog.math.* domain namespaces.
  • Collections.md — standard frog.collections primitives.
  • Text.md — standard frog.text primitives.
  • IO.md — standard frog.io primitives.
  • Image.md — standard frog.image primitives, currently publishing frog.image.decode_file_rgba8 and the portable frog.image.buffer_rgba8 contract.
  • Signal.md — standard frog.signal primitives.
  • Waveform.md — standard frog.waveform value and primitive surface.
  • Table.md — standard frog.table value and primitive surface.
  • System.md — standard frog.system introspection primitives for platform, CPU, memory, process, environment, and capability reads.
  • UI.md — standard frog.ui executable widget interaction primitives.
  • Connectivity.md — transition note indicating that frog.connectivity.* is no longer normatively owned by the intrinsic library layer and is now owned by the Interop profile.
  • Time.md - standard frog.time primitives for wall-clock time, monotonic time, durations, waits, formatting/parsing, and profiling marks.

The presence of Connectivity.md in this directory does not mean that frog.connectivity.* remains part of the intrinsic standardized library core. It is retained only for repository continuity, navigation stability, and explicit architectural redirection.

In practice: 

Libraries/Connectivity.md   -> transition note only
Profiles/Interop.md         -> authoritative normative home

As the widget corridor closes further, this directory is also expected to become the home of the standardized primitive widget baseline, but only in documents whose ownership clearly targets reusable intrinsic widget families rather than source serialization or runtime realization.

7. Intrinsic Library Taxonomy

At the current repository stage, the intrinsic standardized primitive taxonomy is organized as follows:

  • frog.core.* — foundational language primitives
  • frog.math.* — numeric scalar primitives
  • frog.numeric — conservative candidate namespace documented inside Libraries/Math.md for future constants, scalar classification, and explicit conversion/coercion support; not a published v0.1 primitive catalog yet
  • frog.collections.* — collection primitives
  • frog.text.* — text-processing primitives
  • frog.io.* — file, path, resource, and byte-oriented I/O primitives
  • frog.image.* — basic image-data decoding and portable image-buffer primitives; current published primitive: frog.image.decode_file_rgba8
  • frog.signal.* — signal-processing primitives
  • frog.waveform.* — waveform value construction and timing helpers
  • frog.table.* — portable tabular value construction and access
  • frog.system.* — bounded system introspection primitives
  • frog.time.* - wall-clock, monotonic, duration, wait, formatting/parsing, and profiling primitives
  • frog.ui.* — executable widget interaction primitives

The taxonomy can also be read as a simple mental map: 

frog.core.*         -> foundational execution building blocks
frog.math.*         -> scalar numeric operations
frog.numeric        -> candidate numeric support namespace, not yet a v0.1 primitive catalog
frog.collections.*  -> collection manipulation
frog.text.*         -> text processing
frog.io.*           -> file/path/resource/byte I/O
frog.image.*        -> image decoding and image-buffer values
frog.signal.*       -> signal-oriented operations
frog.waveform.*     -> t0/dt/sample waveform values
frog.table.*        -> portable rectangular table values
frog.system.*       -> bounded system introspection
frog.time.*         -> time and timing operations
frog.ui.*           -> object-style widget interaction in execution

The first lightweight-standard taxonomy also classifies each family by its current publication status and by the kind of implementation boundary it implies:

  • value-only: ordinary deterministic value transforms with no host resource dependency,
  • provider-backed: explicit primitives whose implementation may come from a standard-library provider or packaged dependency,
  • runtime-hosted: explicit primitives that need host/runtime services such as UI objects, scheduling, time sources, or managed resources,
  • OS-dependent: explicit primitives whose result depends on platform, filesystem, process, or environment capabilities,
  • profile-owned: standardized optional capability families that are not intrinsic lightweight libraries.
Family Status Purpose Initial scope Out of scope / boundary Implementation posture
frog.core published core Minimal foundational operators and execution building blocks. Arithmetic, comparison, boolean logic, value selection, and explicit local memory through frog.core.delay. Broader math, arrays, text, I/O, UI interaction, profiles, and runtime services. Mostly value-only; delay is explicit local memory governed with the language execution model.
frog.math published lightweight standard library Portable scalar mathematics beyond the minimal core. Utility, rounding, powers, roots, logarithms, trigonometric, and hyperbolic scalar functions. frog.numeric candidate support, linear algebra, statistics, tensors, symbolic math, optimization, hidden random state, and signal processing. Value-only, with numeric edge behavior constrained by the active execution profile.
frog.numeric candidate, documented in Libraries/Math.md Future core-adjacent numeric constants, scalar classification, explicit conversions, and representation helpers. Candidate only; no separate public page and no published v0.1 primitive ids until exact contracts and conformance cases are promoted. Broad mathematics, hidden coercion repair, random generation, signal/waveform/table semantics, and provider-backed numerical domains. Expected to be value-only where promoted, with profile-dependent representation details stated explicitly.
frog.collections published lightweight standard library Portable collection manipulation. Array length, empty check, element get/set, append, concat, and slice. Maps, sets, dictionaries, higher-order collection functions, advanced reshaping, and streaming collections. Value-only. The earlier frog.array candidate is represented by this broader namespace in the current public surface.
frog.text published lightweight standard library Portable text processing over ordinary string values. Concat, length, substring, contains, prefix/suffix predicates, first find, split, and join. Locale collation, regular expressions, rich formatting, parsing, encodings, JSON/XML/HTML, and file/network text I/O. Value-only. The earlier frog.string candidate is represented by frog.text in the current public surface.
frog.io published lightweight standard library Foundational file, path, resource, and byte-oriented access. Path joining/normalization/parent/name, filesystem existence and kind queries, directory listing, whole text reads, and whole byte reads. File mutation, streams, partial reads, networking, hardware I/O, foreign runtime calls, database access, and structured error objects. OS-dependent and runtime-hosted. The earlier frog.path and frog.file candidates are represented by this namespace for v0.1.
frog.image published lightweight standard library Portable image-data values and baseline graphics file decoding. decode_file_rgba8, PNG/JPEG/BMP reads, and the frog.image.buffer_rgba8 value contract. Picture widget realization, camera acquisition, GPU surfaces, advanced computer vision, and non-promoted write/drawing functions. Provider-backed. Codec choice and packaging are implementation details behind the public primitive contract.
frog.signal published lightweight standard library Portable one-dimensional sampled-signal transforms. Sample count, basic analysis, scale/offset, peak normalization, deterministic filtering, decimation, and simple resampling over numeric sample arrays. Waveform records, hardware acquisition, streaming, FFT/spectral analysis, adaptive filters, and multi-channel containers. Value-only for the published v0.1 surface.
frog.ui published intrinsic interaction library Executable widget interaction through object-style and event-oriented primitives. Property read/write, method invoke, event observe, widget-reference consumption, and optional UI sequencing ports. Widget class catalog, front-panel serialization, .wfrog package content, rendering, host realization, and a general async event framework. Runtime-hosted and UI-host mediated, while primitive identity remains public and portable.
frog.time published lightweight standard library Explicit wall-clock, monotonic, duration, wait, formatting/parsing, and diagnostic timing primitives. now, monotonic_now, elapsed helpers, duration conversion/arithmetic, ISO 8601 UTC format/parse, scheduler wait boundaries, periodic target helper, and profiling marks. Hard real-time guarantees, scheduler internals, timer handles, timed loops, wall-clock alarms, locale-heavy formatting, private profiling transports, and OS-specific clock APIs as public law. Mixed value-only and runtime-hosted. Clock reads, waits, and profiling hooks require explicit host capability metadata and local success/error_code status outputs where failure is possible.
frog.waveform published lightweight standard library Portable waveform value helpers around sampled data with timing metadata. Build/unbundle waveform values, access samples, access or update t0 and dt, sample count, contiguous append, and index-to-time conversion. Hardware acquisition, streaming buffers, chart history widgets, device timing, rich attributes, and multi-channel containers. Value-only for the published v0.1 surface; provider/runtime dependencies start only when acquisition or streaming is introduced.
frog.table published lightweight standard library Portable text-cell tabular value construction and access. Build table values, empty tables, row/column counts, headers, rows, cell access, row/column extraction, pure cell/header/row updates, and delimited-text formatting. Database connectivity, spreadsheet automation, table widgets, external data-frame engines, typed cells, row ids, and table view state. Value-only for data-shape helpers; provider-backed only if later formatting/import/export contracts require it.
frog.picture candidate lightweight standard library Picture-value construction and simple 2D drawing. Empty picture, points, lines, rectangles, ovals, arcs, text, pixmap composition, and rasterization candidates. Picture widget realization, advanced graphics engines, GPU drawing, font-engine mandates, and computer vision. Provider-backed where rasterization, text shaping, or image composition needs an implementation module.
frog.plot candidate lightweight standard library Simple plot rendering helpers that produce picture-like values. Waveform, XY, multi-XY, and legend rendering candidates. Chart widgets, live chart history, acquisition, advanced signal analysis, and plotting backends as mandatory dependencies. Provider-backed or value-to-picture depending on the accepted picture model.
frog.boolean deferred candidate Boolean helpers not already covered by frog.core. Possible edge detection, selection helpers, and latch candidates. Core boolean logic already belongs to frog.core; stateful latch behavior must not bypass explicit state and execution semantics. Value-only for stateless helpers; runtime/semantic review required for edge or latch behavior.
frog.sync deferred candidate Communication and synchronization primitives. Queues, notifiers, semaphores, occurrences, and related coordination primitives after execution semantics are settled. Private scheduler internals, unsafe handles, unbounded shared mutable state, and implementation-specific thread APIs. Runtime-hosted and capability-managed; not a value-only library.
frog.ref deferred high-risk candidate Reference-like or protected-value capabilities if accepted later. DVR-like protected values and carefully bounded reference semantics. Raw pointers, arbitrary process memory, hidden aliasing, and unsafe implementation handles as public values. Runtime-hosted and capability-managed; requires source, FIR, lowering, and safety guardrails before publication.
frog.system published lightweight standard library Bounded, read-only system introspection. Platform identifier, architecture, CPU count/load, memory totals/availability, process id, executable path, current directory, environment reads, and FROG capability availability checks. Process execution, process enumeration, OS-specific APIs, permission enumeration, time/timing, hardware inventory, secrets, and making system introspection mandatory for minimal embedded profiles. OS-dependent and runtime-hosted; each call has explicit capability requirements plus local success/error_code status outputs.
frog.process, frog.ffi, frog.net, frog.http, frog.db, frog.registry, frog.com, frog.dotnet profile-owned or future-profile candidates External integration with commands, shared libraries, network services, databases, registries, COM, ActiveX, .NET, and similar ecosystems. Only the surfaces explicitly published by a profile, such as the current Interop profile's frog.connectivity.* family. Intrinsic lightweight-library core. These capabilities depend on host policy, foreign runtimes, external protocols, platform APIs, or security-sensitive boundaries. Profile-owned, OS-dependent, provider-backed, or implementation-specific unless a future public profile standardizes them.

This table is a taxonomy and routing rule. A candidate row does not by itself publish a primitive. A family becomes part of the public standard surface only when its corresponding specification defines concrete primitive identifiers, ports, typing, validation rules, and downstream representation posture.

Additional intrinsic library families MAY be standardized later, but they are not part of the intrinsic standardized surface unless a corresponding specification exists in this directory and is published as such.

The taxonomy is therefore open to disciplined growth, but closed against architectural drift. Intrinsic libraries are added by explicit normative publication, not by convention or by implementation popularity.

8. Libraries vs Profiles

One of the most important architectural rules in the repository is the separation between:

  • intrinsic standardized libraries, and
  • optional standardized profiles.

The distinction is simple: 

If a capability is:
- generic,
- portable,
- intrinsic to the language surface,
- not dependent on a particular external runtime or ecosystem,

then it belongs in Libraries/.

If a capability is:
- optional,
- environment-dependent,
- tied to foreign runtimes, host ABIs, managed platforms, databases,
  protocols, services, target-profile classes, deployment-mode classes,
  or comparable external assumptions,
- standardized but not intrinsic to the minimal core,

then it belongs in Profiles/.

Decision sketch: 

                    New capability
                          |
                          v
         +--------------------------------------+
         | Is it intrinsic, generic, portable, |
         | and broadly language-level?         |
         +-------------------+------------------+
                             |
                   yes       |       no
                             |
                             v
                       Libraries/   -----> evaluate as Profiles/
                                            or implementation-specific extension

Examples:

  • frog.core.add belongs naturally to Libraries/.
  • frog.image.decode_file_rgba8 belongs to Libraries/ when treated as a small, portable, base-distribution image primitive.
  • frog.ui.property_read belongs to Libraries/ because it is part of the intrinsic executable UI interaction surface of the language model.
  • frog.connectivity.* does not belong to the intrinsic library core because it represents an optional interoperability capability surface and is normatively owned by the Interop profile.

This separation keeps the intrinsic language taxonomy durable, predictable, portable, and easier to implement consistently.

The same rule should guide the next widget step: the standardized primitive widget baseline belongs in Libraries/ only insofar as it is intrinsic, portable, and language-level. Anything environment-specific or host-dependent remains outside this core.

9. Naming and Namespaces

FROG primitive identifiers use stable namespace-qualified names. For intrinsic library primitives, the general naming patterns are: 

frog.<library>.<primitive>
frog.<library>.<family>.<primitive>

Examples:

  • frog.core.add
  • frog.math.sqrt
  • frog.collections.length
  • frog.text.concat
  • frog.io.read_text
  • frog.image.decode_file_rgba8
  • frog.signal.moving_average
  • frog.waveform.build
  • frog.table.cell
  • frog.system.platform_info
  • frog.time.monotonic_now
  • frog.ui.property_read

This naming model keeps primitive identity explicit and portable across tools, runtimes, and implementations.

Deeper hierarchical namespaces MAY be used where an intrinsic library family requires explicit sub-namespace ownership.

Other repository layers, including optional profiles, MAY define additional namespace families. Such namespaces are not automatically intrinsic library namespaces merely because they begin with frog.. Architectural ownership is defined by the specification layer that normatively owns them.

In practice: 

Namespace prefix alone is not enough.

"frog.something.*"
does not automatically mean
"intrinsic library namespace".

Normative ownership still matters.

This is especially important in the widget corridor, where:

  • frog.widgets.* identifies widget classes,
  • frog.ui.* identifies executable widget interaction primitives,
  • the two namespaces are related, but not interchangeable.

10. Library Boundaries

The intrinsic standardized library families in this directory are intentionally separated by responsibility.

  • frog.core.* owns only the foundational primitive baseline.
  • frog.math.* owns numeric scalar primitives beyond the core.
  • frog.numeric is only a candidate public namespace documented in Libraries/Math.md until exact primitive contracts are promoted.
  • frog.collections.* owns collection manipulation primitives.
  • frog.text.* owns text-processing primitives.
  • frog.io.* owns file, path, resource, and byte-oriented I/O primitives.
  • frog.image.* owns portable image-data primitives such as decode-to-buffer operations.
  • frog.signal.* owns signal-processing primitives.
  • frog.waveform.* owns waveform value construction, timing access, and sample replacement helpers.
  • frog.table.* owns portable tabular data values and pure table transforms.
  • frog.system.* owns bounded, read-only system introspection primitives.
  • frog.time.* owns explicit time and timing primitives.
  • frog.time.* - wall-clock, monotonic, duration, wait, formatting/parsing, and profiling primitives
  • frog.ui.* owns executable widget interaction primitives only.

Boundary sketch: 

frog.core.*         -> foundational primitives only
frog.math.*         -> math only
frog.numeric        -> candidate numeric support only
frog.collections.*  -> collections only
frog.text.*         -> text only
frog.io.*           -> I/O only
frog.image.*        -> image data only
frog.signal.*       -> signal only
frog.waveform.*     -> waveform values only
frog.table.*        -> tabular values only
frog.system.*       -> system introspection only
frog.time.*         -> time and timing only
frog.ui.*           -> executable UI interaction only

Therefore:

  • frog.core.* MUST NOT become a generic bucket for unrelated future functionality.
  • frog.math.* MUST remain distinct from frog.core.* intrinsic operators and from the candidate frog.numeric support namespace.
  • frog.io.* MUST remain distinct from foreign-runtime interoperability, deployment, database access, and broader external integration concerns unless those are explicitly standardized as intrinsic libraries.
  • frog.image.* MUST remain distinct from Picture widget realization, camera acquisition, advanced computer vision, and implementation-specific codec stacks.
  • frog.ui.* MUST remain distinct from front-panel serialization, widget catalog definition, broader IDE UI editing concerns, target-profile classes, deployment-mode classes, and backend-family-specific UI binding contracts.
  • frog.system.* MUST remain distinct from process execution, networking, file mutation, time/timing, hardware access, permission enumeration, secret access, and host-private runtime service discovery.
  • frog.time.* MUST remain distinct from hard real-time profiles, private scheduler internals, UI event pumps, OS-specific clock APIs, profiling transports, system introspection, and synchronization primitives.
  • frog.text.* MUST remain distinct from file, path, and external-service semantics.
  • frog.collections.* MUST remain distinct from future specialized families unless those are explicitly standardized.
  • frog.signal.* MUST remain distinct from broader acquisition, streaming, tensor, or specialized domain families unless those are explicitly standardized.
  • frog.waveform.* MUST remain distinct from chart widgets, acquisition sessions, streaming buffers, and private waveform-history stores.
  • frog.table.* MUST remain distinct from Table widget state, database cursors, spreadsheets, host grid controls, and external data-frame engines.
  • Future frog.math.linalg, frog.math.fit, frog.math.optimize, and comparable provider-heavy numerical domains MUST preserve explicit status, provider, manifest, and capability boundaries rather than becoming hidden runtime services.
  • Libraries/ MUST NOT become a catch-all container for ecosystem-specific capability growth.
  • Optional capability families that depend on foreign runtimes, host ABIs, managed platforms, databases, protocols, services, target-profile classes, deployment-mode classes, or comparable environment assumptions SHOULD be specified in Profiles/ rather than in Libraries/.

The main anti-pattern to avoid is this: 

Useful capability
      ->
"put it in Libraries/"
      ->
Libraries becomes a catch-all ecosystem bucket
      ->
intrinsic language surface loses clarity

This repository explicitly rejects that drift.

The same warning applies to widget growth: the intrinsic library layer may standardize a primitive reusable widget baseline, but MUST NOT become a dump site for every host-specific front-panel feature or runtime convenience surface.

11. Relation with Other Specification Layers

Library specifications are used together with the rest of the FROG specification. In particular:

  • Expression/Diagram.md defines how primitive nodes appear in executable graphs,
  • Expression/Type.md defines the ordinary type model used by primitive ports,
  • Language/ defines cross-cutting execution semantics that remain distinct from library-local primitive behavior,
  • Expression/Widget.md and Expression/Widget interaction.md define the widget model and source-facing interaction model used by frog.ui.*,
  • Expression/Widget class contract.md defines the class-side legality targeted by frog.ui.*,
  • Profiles/ defines optional standardized capability families that are not part of the intrinsic library core,
  • IDE/Palette.md may organize discovery and presentation of primitives, but does not replace library specifications.

These relationships can be visualized as follows: 

Expression/Diagram.md
        |
        |  references primitive nodes
        v
    Libraries/
        |
        |  provide primitive-local normative contracts
        v
    Language/
        |
        |  provides cross-cutting execution semantics
        v
validated executable meaning

Profiles/
        |
        |  add optional standardized capability families
        v

IDE/Palette.md
        |
        |  exposes discoverability and insertion
        v
does not redefine primitive semantics

Accordingly, a library specification is one normative input used to interpret intrinsic primitive nodes inside a validated executable graph. It is not a replacement for the diagram specification, the language semantics, the profile layer, the widget model, or the IDE model.

12. Relation with IR, Lowering, and Backend Contract

Intrinsic primitive catalogs remain upstream from the execution-facing and backend-facing corridor.

In particular:

  • IR/ MAY carry normalized references to intrinsic primitive identities,
  • IR/Derivation rules.md and IR/Construction rules.md MAY materialize primitive execution objects or support objects that refer to intrinsic primitive contracts,
  • IR/Lowering.md MAY later specialize those primitive-facing execution objects for a backend family,
  • IR/Backend contract.md MAY later declare backend-facing assumptions about primitive consumption,
  • but none of those downstream layers becomes the normative owner of the primitive catalog itself.

The governing rule is: 

Libraries/
    own intrinsic primitive identity and primitive-local contract

IR/
    may represent those primitives in canonical execution-facing derived form

Lowering/
    may specialize execution-facing primitive representation

Backend contract/
    may declare consumable backend-facing primitive assumptions

Implementations/
    may realize those primitives privately

Therefore:

  • a lowered or backend-facing form MUST NOT redefine what frog.core.add or frog.ui.property_write intrinsically are,
  • a compiler, launcher, or runtime MAY realize only the standard-library primitives actually used by a validated program, but that optimization MUST preserve the published primitive contracts,
  • a backend-family-specific consumption model MUST NOT become the normative source of primitive truth,
  • a runtime-private realization of a primitive MUST NOT replace the published primitive-local contract.

This separation is essential because primitive identity must remain stable even when:

  • the canonical IR introduces execution-facing explicitness,
  • lowering changes storage, scheduling, or control realization,
  • backend contracts declare family-specific assumptions,
  • private runtimes choose different internal layouts.

13. Library Evolution

FROG begins with a compact but extensible intrinsic library taxonomy. This is intentional.

The current intrinsic standardized library surface already covers:

  • foundational computation,
  • numeric functions,
  • collections,
  • text processing,
  • I/O,
  • signal processing,
  • waveform values,
  • table values,
  • system introspection,
  • time and timing,
  • widget interaction.

Additional intrinsic library families MAY be added later where they remain:

  • generic,
  • portable,
  • intrinsic to the language surface,
  • not dependent on one specific foreign runtime, managed platform, database stack, host ABI, protocol family, target-profile family, deployment-mode family, backend-family consumption model, or vendor technology.

A lightweight standard library family MAY be shipped with a base FROG distribution while still remaining explicit in source, FIR, lowering, backend contracts, and deployment packaging. The fact that a base distribution provides an implementation does not turn the capability into widget behavior, runtime magic, or vendor-owned semantics.

Capability areas that are useful but environment-dependent SHOULD be specified as profiles or as implementation-specific extensions rather than being folded into the intrinsic library core.

When a new intrinsic library family is introduced:

  • it SHOULD be added as a sibling specification in this directory,
  • it SHOULD define clear namespace ownership,
  • it SHOULD state its relation with Language/, Profiles/, and relevant Expression/ documents,
  • it SHOULD remain compatible with later execution-facing derivation, lowering, and backend-facing consumption without moving those downstream ownerships into Libraries/,
  • it SHOULD be reflected in repository-level architecture and relevant IDE palette documentation where relevant.

For the current widget closure campaign, the next coherent evolution of this directory is to publish a minimal standardized primitive widget baseline whose law remains explicit, whose interaction remains aligned with frog.ui.*, and whose realization remains subordinate rather than normative.

14. Status

At the current repository stage, Libraries/ defines a growing but intentionally controlled intrinsic standardized primitive taxonomy used by the rest of the specification.

Its role is to anchor the normative primitive vocabulary consumed by executable diagrams while remaining cleanly separated from:

  • source-format structure in Expression/,
  • cross-cutting execution semantics in Language/,
  • optional standardized capability families in Profiles/,
  • derived execution-facing representation in IR/,
  • lowering and backend-facing handoff boundaries,
  • widget and front-panel source models,
  • IDE palette organization and authoring workflows,
  • implementation-specific extensions.

The current direction can be summarized simply: 

Libraries/ should stay:
- intrinsic
- portable
- explicit
- bounded
- stable

Libraries/ should not become:
- a profile bucket
- an IR bucket
- a lowering bucket
- a backend-contract bucket
- an IDE bucket
- a runtime bucket
- a vendor bucket
- a generic ecosystem dumping ground

This directory is expected to evolve as the language matures, but that evolution MUST preserve explicit namespace ownership, clear architectural boundaries, and conservative integration with the rest of the specification.

15. Summary

Libraries/ is the architectural home of intrinsic standardized primitive vocabularies in FROG.

It exists to make primitive identity, ports, primitive-local metadata, and primitive-local behavior explicit and portable without corrupting the ownership boundaries of:

  • Expression/,
  • Language/,
  • Profiles/,
  • IR/,
  • IDE/.

Intrinsic libraries stay intrinsic. Optional capability growth stays in profiles. Execution-facing representation stays in IR. Runtime realization stays implementation-private. 

Libraries/
    own intrinsic primitive truth

Profiles/
    own optional capability families

IR/
    owns the canonical execution-facing bridge

Implementations/
    own private realization

For the widget corridor, this means:

  • widget instances remain source-owned in .frog,
  • widget class law remains explicit and inspectable,
  • .wfrog remains the widget-oriented package publication family,
  • frog.ui.* remains the intrinsic executable interaction vocabulary,
  • future primitive widget baseline publication can grow in Libraries/ without collapsing source, behavior, realization, and runtime ownership into one layer.