Skip to content

Interop.md

Latest commit

 

History

History
930 lines (762 loc) · 33.8 KB

Interop.md

File metadata and controls

930 lines (762 loc) · 33.8 KB

FROG logo

🐸 FROG Interop Profile

Optional standardized interoperability profile for FROG
FROG — Free Open Graphical Language

Contents

1. Overview

This document defines the Interop profile for FROG v0.1.

The Interop profile standardizes an optional capability family for interoperability with external execution environments and external data systems.

In v0.1, this profile standardizes a conservative first surface covering:

  • Python request/response invocation,
  • native or shared library request/response invocation,
  • .NET request/response invocation,
  • SQL query and statement execution.

The goal of this first version is to define a practical, bounded, and portable interop surface that fits cleanly within the current FROG diagram and type model while remaining outside the minimal intrinsic library core.

In v0.1, the standardized interop model is intentionally limited to synchronous request/response primitives using explicit textual or byte payloads.

2. Purpose of the Interop Profile

The purpose of this profile is to define a standardized but optional interoperability surface for implementations that choose to support interaction with foreign runtimes, native or managed execution platforms, or SQL-capable data systems.

This profile exists to preserve the architectural distinction between:

  • the minimal core language surface,
  • portable intrinsic standardized libraries,
  • optional standardized capability families,
  • implementation-specific extensions.

Accordingly, the Interop profile is standardized but optional. Support for this profile is not required for core FROG conformance.

3. Relation with Other Specifications

This document complements the following specifications:

  • Profiles/Readme.md — defines the architectural role of optional standardized capability families.
  • Expression/Diagram.md — defines how Interop profile primitives appear as executable diagram nodes.
  • Expression/Type.md — defines the ordinary scalar and array types used by these primitives.
  • Language/ — defines the cross-cutting execution semantics that remain authoritative for validated programs.
  • Libraries/Core.md — defines the minimal always-available computational primitives, which remain distinct from interop capability.
  • Libraries/IO.md — defines file, path, byte, and related resource I/O primitives, which remain distinct from foreign-runtime and SQL interoperability.
  • Libraries/UI.md — defines widget interaction primitives, which remain distinct from interop primitives.
  • Libraries/Connectivity.md — retained only as a transition note and MUST NOT be treated as the primary normative source for this profile.
  • GOVERNANCE.md — defines governance-facing distinctions such as core support, profile support, conformance, certification, and branding-related claims.

This document defines the standardized primitive catalog for the Interop profile. It does not redefine the graph model, the core type model, the general execution semantics, or the widget interaction model.

4. Architectural Role

The Interop profile provides standardized primitives for invoking capabilities that are external to the ordinary FROG function model and external to the intrinsic primitive core.

In serialized diagrams, calls to these primitives are represented as primitive nodes whose type field uses the frog.connectivity.* namespace.

Examples: 

frog.connectivity.python.call_text
frog.connectivity.native.call_bytes
frog.connectivity.dotnet.call_text
frog.connectivity.sql.query_text
frog.connectivity.sql.execute

The Interop profile is distinct from:

  • frog.core, which contains the minimal always-available computational primitives,
  • frog.io, which covers file, path, byte, and related resource I/O only,
  • frog.ui, which covers widget interaction only,
  • future Interop subprofiles or separate optional profiles for process execution, networking, HTTP, host input devices, hardware access, runtime coordination, deployment, or richer external capability families.

This profile standardizes an optional capability family. It does not require that every FROG implementation support foreign runtimes, native ABI invocation, managed-platform execution, or SQL integration.

5. Profile Identity and Namespace

The stable identity of this profile is: 

Interop profile

This profile owns the standardized optional primitive namespace family: 

frog.connectivity.*

For this profile, the general naming pattern is: 

frog.connectivity.<family>.<primitive>

Examples:

  • frog.connectivity.python.call_text
  • frog.connectivity.python.call_bytes
  • frog.connectivity.native.call_bytes
  • frog.connectivity.dotnet.call_text
  • frog.connectivity.sql.query_text
  • frog.connectivity.sql.execute

Primitive and family names in frog.connectivity SHOULD use lowercase snake_case where multiple words are needed.

The namespace remains stable even though its architectural ownership belongs to the Interop profile rather than to the intrinsic standard library core.

6. Scope for v0.1

FROG v0.1 standardizes the following Interop profile primitive families:

  • Python request/response invocation primitives,
  • native or shared library request/response invocation primitives,
  • .NET request/response invocation primitives,
  • SQL query and statement execution primitives.

For v0.1, these families remain in a single Interop profile document. The profile owns frog.connectivity.* as an optional capability namespace, while each family remains claimable only to the extent explicitly defined here or by a later profile revision.

The following table records the public routing posture for current and future connectivity families:

Family Namespace posture v0.1 status Boundary
Python request/response frog.connectivity.python.* Published in this profile. Source-visible session handles, interpreter lifecycle objects, and environment selection contracts are deferred.
Native or shared-library request/response frog.connectivity.native.* Published in this profile as byte request/response. Typed FFI, calling-convention catalogs, structured ABI parameters, and memory ownership contracts are deferred.
.NET request/response frog.connectivity.dotnet.* Published in this profile as textual request/response. Managed object handles, reflection surfaces, COM, ActiveX, and arbitrary object-graph interop are deferred.
SQL query and execute frog.connectivity.sql.* Published in this profile as minimal query and execute primitives. Connection handles, prepared statements, transactions, cursors, pooling, and row streaming are deferred.
Process and command execution frog.connectivity.process.* or a later process subprofile Not published in v0.1. Requires explicit argv versus shell execution, stdin/stdout/stderr, working directory, environment, timeout, exit status, security policy, and async-spawn boundaries.
TCP sockets frog.connectivity.tcp.* or a later low-level socket subprofile Not published in v0.1. Requires explicit open, listen, accept, read, write, close, address, port, timeout, cancellation, backpressure, and session-lifetime rules.
UDP sockets frog.connectivity.udp.* or a later datagram subprofile Not published in v0.1. Requires datagram-size, source/destination addressing, multicast, broadcast, packet loss, ordering, timeout, and host-policy rules.
TLS frog.connectivity.tls.* or a later secure-transport subprofile Not published in v0.1. Requires certificate, key, trust store, hostname verification, protocol-version, cipher, client/server handshake, and secret-handling policy.
HTTP client frog.connectivity.http.* or a later HTTP subprofile Not published in v0.1. Requires methods, URL, headers, body, status code, redirects, authentication, cookies, proxy policy, TLS policy, streaming, and secret handling.
WebSocket frog.connectivity.websocket.* or a later streaming subprofile Not published in v0.1. Requires session handles, message framing, close codes, ping/pong, ordering, reconnect, TLS, backpressure, and async/event semantics.
File transfer frog.connectivity.file_transfer.* or narrower WebDAV, SFTP, FTPS, or HTTPS-backed subprofiles Not published in v0.1. Requires remote path semantics, credentials, upload/download operations, directory listing, overwrite policy, resumability, TLS/trust policy, and legacy-protocol gates for FTP-style surfaces.
Mail frog.connectivity.mail.* or a later SMTP-oriented subprofile Not published in v0.1. Requires send-only versus receive-capable scope, MIME attachment handling, authentication, TLS, server policy, and secret handling. IMAP and POP-style receive surfaces are deferred.
Instrument and serial I/O frog.instrument.* or a separate instrument-control profile, not intrinsic connectivity core Not published in v0.1. Requires a distinct instrument-resource model for serial, GPIB, USB, Ethernet, PXI, VXI, or comparable message I/O and should not be hidden inside generic network connectivity.
Bluetooth and legacy infrared frog.connectivity.bluetooth.* or legacy-only profile material Not published in v0.1. Requires discovery, pairing, permissions, listener lifecycle, read/write semantics, platform gates, and explicit legacy/deferred posture for IrDA-style surfaces.
RPC frog.connectivity.rpc.* or narrower gRPC, Protobuf, or JSON-RPC subprofiles Not published in v0.1. Requires schema ownership, service/method identity, streaming posture, generated bindings, versioning, authentication, and compatibility policy.
IoT and messaging frog.connectivity.iot_messaging.* or narrower MQTT/AMQP subprofiles Not published in v0.1. Requires broker/session identity, topics, QoS, acknowledgements, reconnect, buffering, credentials, TLS, and delivery-order policy.
Industrial protocols frog.connectivity.industrial.* or separate industrial profile set Not published in v0.1. Requires protocol-specific data models, bus/device identity, real-time or fieldbus constraints, safety policy, and optional families such as Modbus, OPC UA, EPICS, CAN, LIN, FlexRay, or EtherCAT.
Host input devices frog.connectivity.input_device.* or a later host-input subprofile Not published in v0.1. Requires platform gates, device discovery, open/acquire/close lifecycle, polling semantics, status behavior, and distinction from FROG UI widget events.
Windows-specific system interop frog.connectivity.windows.* or narrower Windows subprofiles Not published in v0.1, except the existing bounded .NET request/response family. Registry, COM, ActiveX, and broader managed-runtime integration require explicit platform, trust, threading, object lifetime, and capability policy.
Service hosting, callbacks, and live data Later profile or profile revision only Not published in v0.1. Requires lifecycle, routing, concurrency, subscription, buffering, reconnection, security, and async/session semantics.

These future families are reserved only as routing posture. Their names, ports, capability tokens, and conformance claims are not standardized until a future profile document or profile revision publishes them explicitly.

These primitives provide a first standardized interoperability layer for:

  • Python modules and functions,
  • native or shared library entry points, including C-compatible or C++-compatible host-call surfaces exposed by a supporting implementation,
  • .NET assemblies, types, and methods,
  • SQL-capable data sources addressed by a supporting implementation.

FROG v0.1 does not attempt to define:

  • persistent source-level handles or sessions,
  • process or command execution primitives,
  • source-visible Python session lifecycle primitives,
  • typed foreign-function or ABI call nodes beyond the byte request/response native primitive,
  • callbacks, event subscriptions, or bidirectional host integration,
  • async or streaming interop,
  • TCP, UDP, TLS, HTTP, WebSocket, FTP, WebDAV, SFTP, SMTP, MQTT, AMQP, RPC, gRPC, or industrial-protocol primitives,
  • keyboard, mouse, joystick, game controller, or other host input-device acquisition primitives,
  • serial, GPIB, USB, Ethernet, PXI, VXI, instrument-resource message I/O, or fieldbus-specific communication primitives,
  • object-graph reflection as a standard source-level mechanism,
  • prepared statements, transactions, cursors, or connection pooling as source-level standardized objects,
  • automatic marshaling of arbitrary FROG values into foreign object systems,
  • COM, ActiveX, Java, gRPC, REST, message-bus, or general network transport primitives,
  • generic external-runtime or external-service bindings beyond the explicit primitive families standardized here.

7. Interop Model

In v0.1, standardized interop primitives are synchronous request/response operations.

An interop primitive consumes explicit inputs, performs one external interaction, and then produces ordinary FROG outputs.

The standardized source-level model does not expose persistent foreign references, runtime sessions, connection handles, or foreign object identities as first-class FROG values.

Accordingly:

  • each standardized call in this document is self-contained at source level,
  • implementations MAY internally reuse connections, runtimes, processes, drivers, or pools,
  • such reuse remains implementation-defined unless another applicable specification standardizes it,
  • such reuse is not part of the canonical source contract defined here.

Binding resolution, host process model, security policy, timeout policy, foreign runtime availability, driver availability, platform availability, and concrete execution environment are implementation-defined unless standardized elsewhere.

This document standardizes the source-visible primitive contract only. Implementation-defined binding does not make an unsupported family valid: a program that references a frog.connectivity.* primitive outside the supported profile or subset must be rejected or reported through the implementation's unsupported-profile or unsupported-subset diagnostic model.

8. Payload Model

All Interop profile primitives are typed according to Expression/Type.md.

Because FROG v0.1 does not yet standardize records, structs, enums, class types, or variant types, the minimal standardized interop payload model uses only built-in scalar and array types.

In v0.1, the following built-in types are especially relevant to this profile:

  • string — used for identifiers, textual requests, textual responses, SQL text, and serialized parameter documents,
  • bool — used for success signaling,
  • i64 — used for affected-row counts,
  • array<u8> — used for raw binary requests and responses.

Unless stated otherwise:

  • all required inputs MUST exist and be type-compatible,
  • all outputs MUST always be present,
  • primitives that can fail MUST expose a success output of type bool,
  • when success = false, every data output MUST still be well-typed and MUST take its defined fallback value.

This profile does not standardize an error-object output, exception payload, or diagnostic record as part of the source-visible primitive contract in v0.1. Failure is exposed only through success together with the standardized fallback value of each data output.

Fallback values in this document are standardized as follows:

  • empty string: "",
  • zero affected rows: 0,
  • empty dynamic byte array: array<u8> with zero elements.

When a primitive uses a textual request or textual response payload, the semantic meaning of that payload is defined by the supporting implementation or by another applicable specification. For example, an implementation MAY use JSON text, SQL parameter text, or another stable textual interchange form.

When a primitive uses a byte payload, the semantic meaning of that payload is likewise defined by the supporting implementation or by another applicable specification.

9. Python Primitives

9.1 frog.connectivity.python.call_text

Invokes a Python function using a textual request payload and returns a textual response payload.

  • input ports: module, function, request
  • output ports: response, success

Types:

  • module: string
  • function: string
  • request: string
  • response: string
  • success: bool

Rules:

  • if success = true, response contains the textual result produced by the addressed Python function,
  • if success = false, response MUST be the empty string,
  • Python environment resolution, import rules, and function dispatch are implementation-defined unless standardized elsewhere.

9.2 frog.connectivity.python.call_bytes

Invokes a Python function using a byte request payload and returns a byte response payload.

  • input ports: module, function, request
  • output ports: response, success

Types:

  • module: string
  • function: string
  • request: array<u8>
  • response: array<u8>
  • success: bool

Rules:

  • if success = true, response contains the byte result produced by the addressed Python function,
  • if success = false, response MUST be the empty byte array,
  • Python environment resolution, import rules, and function dispatch are implementation-defined unless standardized elsewhere.

10. Native and Shared Library Primitives

10.1 frog.connectivity.native.call_bytes

Invokes an entry point from a native or shared library using a byte request payload and returns a byte response payload.

  • input ports: library, symbol, request
  • output ports: response, success

Types:

  • library: string
  • symbol: string
  • request: array<u8>
  • response: array<u8>
  • success: bool

Rules:

  • if success = true, response contains the byte result produced by the addressed native or shared-library entry point,
  • if success = false, response MUST be the empty byte array,
  • library resolution, calling convention, symbol visibility, ABI compatibility, and memory ownership rules are implementation-defined unless standardized elsewhere.

11. .NET Primitives

11.1 frog.connectivity.dotnet.call_text

Invokes a .NET method using a textual request payload and returns a textual response payload.

  • input ports: assembly, type_name, method, request
  • output ports: response, success

Types:

  • assembly: string
  • type_name: string
  • method: string
  • request: string
  • response: string
  • success: bool

Rules:

  • if success = true, response contains the textual result produced by the addressed .NET method,
  • if success = false, response MUST be the empty string,
  • assembly resolution, type lookup, method binding, runtime loading, and instance-versus-static dispatch policy are implementation-defined unless standardized elsewhere.

12. SQL Primitives

12.1 frog.connectivity.sql.query_text

Executes a SQL query and returns a textual result document.

  • input ports: connection, query, parameters
  • output ports: rows, success

Types:

  • connection: string
  • query: string
  • parameters: string
  • rows: string
  • success: bool

Rules:

  • if success = true, rows contains the query result encoded as a textual result document,
  • if success = false, rows MUST be the empty string,
  • the textual form of parameters is implementation-defined unless standardized elsewhere,
  • connection-string interpretation, driver selection, dialect behavior, and result encoding are implementation-defined unless standardized elsewhere.

12.2 frog.connectivity.sql.execute

Executes a non-query SQL statement and returns an affected-row count.

  • input ports: connection, query, parameters
  • output ports: affected_rows, success

Types:

  • connection: string
  • query: string
  • parameters: string
  • affected_rows: i64
  • success: bool

Rules:

  • if success = true, affected_rows contains the affected-row count produced by the supporting implementation,
  • if success = false, affected_rows MUST be 0,
  • the textual form of parameters is implementation-defined unless standardized elsewhere,
  • connection-string interpretation, driver selection, dialect behavior, and affected-row semantics are implementation-defined unless standardized elsewhere.

In v0.1, SQL primitives do not standardize source-level transactions, prepared-statement handles, cursor iteration, or connection lifetime control.

13. Diagram Representation

Calls to Interop profile primitives are serialized as primitive nodes in the diagram.

Examples: 

{
  "id": "py_eval_1",
  "kind": "primitive",
  "type": "frog.connectivity.python.call_text"
}

{
  "id": "native_call_1",
  "kind": "primitive",
  "type": "frog.connectivity.native.call_bytes"
}

{
  "id": "sql_query_1",
  "kind": "primitive",
  "type": "frog.connectivity.sql.query_text"
}

The exact port existence, direction, and typing of these nodes are resolved from this specification together with the type model and the graph rules.

14. Validation Rules

Implementations that claim support for the Interop profile MUST enforce the following rules:

  • every frog.connectivity primitive reference MUST identify a valid standardized Interop profile primitive name,
  • all required input ports MUST exist and be type-compatible,
  • all produced output ports MUST match the primitive definition,
  • all identifier-like selector ports in this document MUST use type string in v0.1,
  • all byte payload ports in this document MUST use type array<u8>,
  • all success outputs MUST use type bool.

For result-bearing primitives:

  • a success output MUST exist,
  • fallback values for unsuccessful results MUST match the definitions in this specification.

For frog.connectivity.sql.execute:

  • affected_rows MUST use type i64.

An implementation that does not support this profile MUST NOT silently reinterpret frog.connectivity.* primitives as intrinsic-library primitives. Unsupported profile usage MUST instead be rejected or reported as unsupported according to the implementation's validation or capability-reporting model.

An implementation that supports only a subset of this profile MUST likewise reject or report primitives outside its claimed subset. For example, support for frog.connectivity.python.* does not imply support for frog.connectivity.sql.*, future process execution primitives, future HTTP primitives, or future host input-device primitives.

15. Support and Capability Claims

Support for the Interop profile is optional.

A core-conforming FROG implementation MAY support none of the primitives defined here.

An implementation claiming support for the Interop profile SHOULD support the full set of primitives defined by this document unless a future narrower subprofile, profile revision, or explicit subset-claim model is standardized.

Accordingly:

  • core FROG support only is a valid claim,
  • core FROG + Interop profile is a stronger claim,
  • a partial implementation MUST NOT present itself as full Interop profile support unless the supported subset is made explicit.

Examples of explicit non-full claims may include implementation wording such as:

  • core FROG + Python interop subset
  • core FROG + SQL interop subset
  • core FROG + partial frog.connectivity support

Future subprofiles may make narrower claims first-class, such as a process execution subset, a TCP/UDP socket subset, a TLS subset, an HTTP client subset, a WebSocket subset, a file-transfer subset, a mail subset, a typed native FFI subset, an input-device subset, an RPC subset, an IoT messaging subset, an industrial-protocol subset, or a Windows-specific subset. Until such documents are published, those claims are descriptive implementation claims rather than full standardized Interop profile claims.

Capability claims under this document do not automatically imply certification, trademark permission, official endorsement, or branding authorization.

16. Out of Scope for v0.1

  • persistent foreign handles or object references as source-level standardized values,
  • process launch, shell execution, background process management, stdout/stderr streaming, or OS command nodes,
  • standardized reflection over Python objects, .NET objects, or native ABI structures,
  • standardized Python interpreter sessions, virtual-environment selection, or reusable scripting-session objects,
  • automatic bidirectional mapping between arbitrary FROG values and foreign structured types,
  • typed ABI configuration for native/shared-library calls beyond the byte request/response primitive,
  • callbacks and re-entrant invocation into FROG graphs,
  • transaction control primitives such as begin, commit, and rollback,
  • prepared statements, cursors, and row-by-row iteration,
  • network protocols such as HTTP, TCP, UDP, WebSocket, MQTT, or gRPC,
  • TLS configuration, certificate/trust material, or cryptographic provider selection,
  • file-transfer protocols such as FTP, FTPS, SFTP, WebDAV, SCP, or remote filesystem synchronization,
  • mail protocols such as SMTP, SMTPS, IMAP, or POP3,
  • instrument-control protocols, serial message I/O, or fieldbus families such as Modbus, OPC UA, EPICS, CAN, LIN, FlexRay, or EtherCAT,
  • host input-device discovery or acquisition for keyboards, mice, joysticks, game controllers, or comparable devices,
  • COM, ActiveX, Java, or other non-listed foreign platforms,
  • generic external-runtime or external-service primitives beyond the explicit families standardized here,
  • async execution, futures, promises, channels, or runtime scheduling primitives,
  • source-level error objects, exception payload channels, or standardized diagnostic record transport.

17. Summary

The Interop profile defines a minimal optional standardized interoperability surface for FROG v0.1.

It standardizes conservative request/response primitives for Python, native or shared libraries, .NET, and SQL while remaining compatible with the current FROG source and type model.

In short:

  • frog.io covers file, path, byte, and related resource I/O,
  • frog.ui covers widget interaction,
  • frog.connectivity covers optional standardized interoperability with foreign runtimes, native or shared libraries, managed platforms, and SQL-capable data sources,
  • richer sessions, handles, callbacks, broader service bindings, and async coordination remain for later revisions.