cortex_link Module

Phase G: §11.4 of the master spec. The C shim provides a BSD-sockets (POSIX) and a Winsock2 (Windows) backend, so attached mode runs on Linux, macOS, and Windows alike.


Uses


Variables

Type Visibility Attributes Name Initial
integer(kind=int64), public, parameter :: MAX_FRAME_BYTES = 64_int64*1024_int64*1024_int64

Upper bound on a single length-prefixed INBOUND frame field (header or payload), enforced before allocation in =cortex_recv_frame=. The Cortex peer is on the loopback TCP port, but it is still untrusted input: without a cap a buggy/compromised peer can request ~4 GiB per field and exhaust memory. 64 MiB is generously above any legitimate request frame (headers are small JSON; bulk binary data rides the COPY_SOLUTION reply, which the worker sizes itself, not an inbound request). This cap deliberately does NOT apply to the send path — see =MAX_SEND_FRAME_BYTES=.
integer(kind=int64), public, parameter :: MAX_SEND_FRAME_BYTES = 4294967295_int64

Upper bound on an OUTBOUND frame field: the u32 wire length prefix (spec §12.2) can express at most 2^32-1 bytes. Legitimate COPY_SOLUTION replies routinely exceed the 64 MiB inbound cap (any 2D grid past ~1182² with 6 primitives), so the send side must not reuse =MAX_FRAME_BYTES= (audit 2026-07-06 N1). Handlers that build bulk replies pre-check against this limit and return a reply-level error instead of ever tripping the fatal send-side guard.

Interfaces

interface

  • private function c_cortex_connect_tcp(host, port) result(fd) bind(C, name="cortex_connect_tcp"))

    Arguments

    Type IntentOptional Attributes Name
    character(kind=c_char, len=1), intent(in) :: host(*)
    integer(kind=c_int), value :: port

    Return Value integer(kind=c_int)

interface

  • private function c_cortex_send_all(fd, buf, n) result(r) bind(C, name="cortex_send_all"))

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=c_int), value :: fd
    type(c_ptr), value :: buf
    integer(kind=c_size_t), value :: n

    Return Value integer(kind=c_size_t)

interface

  • private function c_cortex_recv_all(fd, buf, n) result(r) bind(C, name="cortex_recv_all"))

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=c_int), value :: fd
    type(c_ptr), value :: buf
    integer(kind=c_size_t), value :: n

    Return Value integer(kind=c_size_t)

interface

  • private function c_cortex_close(fd) result(r) bind(C, name="cortex_close"))

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=c_int), value :: fd

    Return Value integer(kind=c_int)


Functions

public pure function be_u32_to_i64(buf) result(n)

Decode a 4-byte big-endian length prefix as an UNSIGNED 32-bit value widened to int64. Each byte is masked into int64 before the shift/OR, so a wire value with the high bit set (0x80000000.. 0xFFFFFFFF) decodes as a large positive int64 — not a negative int32 (the desync bug). Range: [0, 4294967295].

Arguments

Type IntentOptional Attributes Name
integer(kind=int8), intent(in) :: buf(4)

Return Value integer(kind=int64)

public pure function is_frame_len_valid(n) result(ok)

A decoded frame length is acceptable iff it is non-negative and within the =MAX_FRAME_BYTES= cap. (Non-negativity is structurally guaranteed by =be_u32_to_i64=, but kept explicit so the predicate is correct for any int64 caller.)

Arguments

Type IntentOptional Attributes Name
integer(kind=int64), intent(in) :: n

Return Value logical

public pure function is_send_frame_valid(n) result(ok)

Check that a send-side frame field (header or payload) can be represented by the u32 wire length prefix. Deliberately NOT symmetric with =is_frame_len_valid=: the 64 MiB inbound cap guards against an untrusted peer's request sizes, while outbound frames are sized by the worker itself and legitimately carry bulk COPY_SOLUTION replies far beyond 64 MiB (audit 2026-07-06 N1).

Arguments

Type IntentOptional Attributes Name
integer(kind=int64), intent(in) :: n

Return Value logical


Subroutines

public subroutine parse_uri(uri, host, port)

Parse a "tcp://host:port" URI into host string and integer port. Errors fatally on a malformed URI — bug in the caller.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: uri
character(len=*), intent(out) :: host
integer, intent(out) :: port

public subroutine cortex_open(uri, fd)

Open a TCP loopback connection to the Cortex server.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: uri
integer, intent(out) :: fd

public subroutine cortex_send_frame(fd, header, payload)

Send a length-prefixed frame: 4-byte BE header length, header bytes, 4-byte BE payload length, payload bytes. Both length prefixes are always present (payload length is zero when payload is empty; spec §12.2).

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: fd
integer(kind=int8), intent(in), target :: header(:)
integer(kind=int8), intent(in), target :: payload(:)

public subroutine cortex_recv_frame(fd, header, payload)

Receive a length-prefixed frame. Both header and payload are returned as allocatable byte arrays (caller owns).

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: fd
integer(kind=int8), intent(out), allocatable :: header(:)
integer(kind=int8), intent(out), allocatable :: payload(:)

public subroutine cortex_close_fd(fd)

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: fd

private subroutine send_bytes(fd, buf)

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: fd
integer(kind=int8), intent(in), target :: buf(:)

private subroutine recv_bytes(fd, buf)

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: fd
integer(kind=int8), intent(inout), target :: buf(:)

private pure subroutine pack_be_u32(n, out)

Pack an UNSIGNED 32-bit length prefix from an int64 value in [0, 4294967295]. Takes int64 so a length in (2^31-1, 2^32-1] — legitimate for large COPY_SOLUTION replies — never round-trips through int32 (an out-of-range conversion, processor-dependent). Inverse of =be_u32_to_i64=.

Arguments

Type IntentOptional Attributes Name
integer(kind=int64), intent(in) :: n
integer(kind=int8), intent(out) :: out(4)