XU XUv0.13.1
中文

#xacp

import: #xacp

counts: 58 functions, 4 methods, 11 types, 29 constants, 0 method sets

#xacp is the transport-neutral safety core published with the Xu 0.13.1 SDK: frame limits, XUN checks, permissions, and session lifetime. Importing it does not open a control channel. Stdio and loopback TCP are runtime hooks inserted only by xu build --xacp or --xacp-port.

CLI: xu xacp · FAQ · Matching release source · Development protocol

The API declarations are source-reviewed against the selected release. The bounded ui.record sampling contract below follows §7 of the development protocol. Native stdio/TCP sessions, UI attachment, screenshots, and platform acceptance remain unverified.

Session

open_session() returns a session in STATE_NEW (0) with PERM_NONE, generation 1, and the next request id 1. close_session moves it to STATE_CLOSED (2), bumps the generation, clears the active request, and drops permissions. STATE_OPEN is 1.

Only one request may be active. begin_request checks authorization and accepts only a positive id equal to next_id, reserves it, and advances the next id. An invalid id returns invalid_request_id; a second active request returns request_in_flight. A non-hello first request closes the session with hello_required. finish_request checks the active id and generation (stale_request on mismatch). A successfully negotiated hello opens the session; an unnegotiated hello cannot open it. Closed sessions return session_closed.

FunctionRole
open_session() SessionNew session, no permissions.
close_session(s $&Session)Close and clear permissions.
cancel_request(s $&Session)Drop the active request without opening the session.
begin_request(s $&Session, r &Request) OutcomeReserve the next monotonic id when authorized allows it.
finish_request(s $&Session, id int) OutcomeRelease the active id. Id 1 opens the session.
authorized(s $&Session, r &Request) boolxacp.hello only in STATE_NEW. Later ops need their permission bit.
dispatch(s $&Session, d &xun.Doc, l &Limits) OutcomeCore lifecycle only. Completes xacp.hello. Does not grant development permissions. Every other known op returns not_implemented after a successful begin, or permission_denied when unauthorized.

Hello and permissions

Permission changes are host policy. set_permissions succeeds only while the session is still STATE_NEW, and only for bits inside 0..15. Unknown bits are rejected. After a request has been finished, permissions stay as they are.

ConstantValueOperations
PERM_NONE0xacp.hello, and only from STATE_NEW
PERM_INFO1proc.status
PERM_PROCESS2proc.output
PERM_UI_READ4ui.tree, ui.screenshot, ui.record
PERM_UI_MUTATE8ui.input, ui.act
PERM_ALL15development_permissions() and enable_development()

enable_development(s) is an explicit host helper equivalent to set_permissions(s, PERM_ALL). It does not bypass schema checks, session lifetime, native-resource disposal, or limits. Calling it after hello finishes returns false. Startup and attachment servers instead read XU_XACP_TOKEN and call negotiate_hello after a validated hello has begun and before finish_request.

Hello requires ver: !ver 1.0.0 and a non-empty string nonce, which the response echoes. With no host token configured, grants are capped at PERM_INFO, even if the client sends a token. With a host token, missing or mismatched args.token returns auth_failed and closes the session; a matching token allows up to PERM_ALL (15 in this SDK). Optional args.permissions is an !i mask of known bits: the grant is its intersection with the host allowance. Omitting it requests that allowance. Responses include numeric permissions and permission_label (none, info, development, or custom).

Frames and limits

Both transports use XACP/1\n<N>\n followed by exactly N bytes of plain XUN. Header lines end in LF (0x0A); N is a positive ASCII decimal byte count excluding the header. Count UTF-8 bytes, including any newline in the body. There is no closing delimiter or extra separator between frames. The transport strips the prefix and reads exactly N bytes before calling parse_frame(body). That function accepts only the XUN body and rejects an empty body, invalid XUN, or a body above MAX_FRAME_BYTES. validate_request requires a root dictionary containing exactly id, op, and args; id is a positive !i.

default_limits() uses these hard caps. A custom Limits value may only be smaller.

ConstantValue
MAX_FRAME_BYTES1048576 (1 MiB)
MAX_STRING_BYTES65536
MAX_FIELDS64
MAX_TABLE_ROWS10000
MAX_NODE_ID16777215

consume_input and consume_output reject negative counts, single counts above the frame cap, and totals above the session byte budget. The startup reader returns frame_too_large for an oversized body and truncated_frame for EOF inside a header or body. Clean EOF at a frame boundary closes the session. Frame errors use id 0; schema errors use a valid id hint when available, otherwise 0. Frame, schema, and authentication errors close the session.

This hello has a 69-byte body and a 10-byte header (79 bytes total). Every displayed line ends in LF, including the nonce line:

XACP/1
69
id: !i 1
op: xacp.hello
args:
  ver: !ver 1.0.0
  nonce: docs-client

With no host token configured, the matching response has a 109-byte body (120 bytes including its header). The last line again ends in LF. Responses use the same length prefix, with id, ok, and either data or error.code (plus optional error.msg). The next frame starts immediately after the body:

XACP/1
109
id: !i 1
ok: !b true
data:
  state: OPEN
  nonce: "docs-client"
  permissions: !i 1
  permission_label: info

Known operations

The schema allows only these operations. Anything else is an unknown operation.

OpPermissionStartup control channel
xacp.helloPERM_NONE, STATE_NEW onlyToken and permission negotiation before finish. Returns state: OPEN, echoed nonce, numeric permissions, and a permission label.
proc.statusPERM_INFOEmpty args. Returns the real os.getpid() and state: OPEN.
proc.outputPERM_PROCESSSchema-checked (stream is stdout or stderr). Returns not_implemented with no output adapter.
ui.treePERM_UI_READSchema-checked. Returns not_implemented with no Screen adapter.
ui.screenshotPERM_UI_READSame. No live pixels on this channel.
ui.inputPERM_UI_MUTATESame, including after step checks.
ui.actPERM_UI_MUTATESame. Allowed action names in the schema are focus, click, set_text, and set_checked.
ui.recordPERM_UI_READSame. Schema modes are events and frames. This is not the launcher's stdout record mode.

On the startup channel, not_implemented is returned after begin_request, so that id is consumed and the next frame must use the following id. permission_denied is returned before the id advances.

UI control requires an explicit attach_stdio or attach_tcp handle, a live ui/widgets.Screen registered with register_screen, and poll calls from the Screen-owning coroutine between UI event iterations. Business main continues on this path. Unregister before leaving the poll loop. Typed helpers (ui_tree, ui_screenshot, ui_input, ui_act, and recorder helpers) still require the matching permission and check window/node ids, scale (0.1 through 4.0), text, and row/event budgets. A screenshot returns an owning draw.Surface; the caller disposes it. Startup --xacp-stdio and --xacp-tcp do not register a Screen. End-to-end UI behavior remains unverified.

Bounded UI recording

With a matching registered Screen, ui.record performs bounded, pull-style XAR1 sampling within a single request. It requires PERM_UI_READ, a positive win: !i, and mode: events|frames. The Screen owner starts an in-memory bounded StreamWriter, samples synchronously, and finishes the recorder before responding. The optional arguments are:

ArgumentDefaultBound and meaning
max_bytes: !i65536, reduced to fit the response1..limits.max_frame_bytes; cumulative XAR1 bytes, including headers and trailing LF.
max_records: !i64At least 1; maximum complete records in this segment.
duration_ms: !i00..limits.request_timeout_ms - 1; 0 takes one immediate sample, positive values bound the sampling window.

Unknown fields, wrong types, or invalid bounds return schema_error. Between samples the recorder sleeps for up to 10 ms, stopping at the duration or record/byte budget; request queue time reduces the available window. Each success contains mode, records: !i, bytes: !i, truncated: !b, and payload, a quoted XAR1 string containing only complete records. truncated=true means the byte or record budget was exhausted; reaching the requested duration alone is normal completion. The effective byte budget is at most (limits.max_frame_bytes - 256) / 2 to reserve envelope and string-escape space, and the serialized response is also checked against the frame limit.

If the first record cannot fit, or a sink/snapshot fails, the recorder is aborted and the request returns adapter_error. A later record that cannot fit returns the completed prefix with truncated=true. The response uses the normal XU_XACP_WRITE_TIMEOUT_MS frame write deadline.

events emits current-state observations labelled state=true, with window, canvas, generation, and open. Screen has no public input event history/subscription, so these are not a real input event log. frames uses screen_screenshot then surface_record, exporting dimensions only with redacted=true and no pixels; each native Surface is disposed before continuing. Sampling neither injects input nor requires PERM_UI_MUTATE. It does not pump the application's UI event loop or reconstruct events between requests.

Clients pull successive segments by repeating ui.record. Each segment starts at sequence 1, with no persistent recorder or continuation cursor, and each request has exactly one XACP/1 response. Without a Screen, the result is not_implemented; a foreign or closed window returns stale_window. stream_required is reserved for adapters without a sink/sampling capability and is not returned by the supplied Screen sampling path. Platform support follows the registered Screen and its snapshot backend, including Windows.

Library start_recorder / write_record / finish_recorder also accept other StreamWriter sinks; callers must abort_recorder on failure. Library users with an input source can write input_record payloads. XAR1 segments are distinct from CLI xu xacp record, which captures stdout. The full recording contract is in PROTOCOL.md §7 on dev.

Transport hooks

src/xacp/stdio.xu is part of the same package, and an --xacp build inserts stdio_preflight(port) at the start of main. That is the control entry. A normal import of #xacp does not emit it.

--xacp-help is a separate startup print, not a control session. Its capabilities line is stdio. When the build port is 0 it also prints tcp: disabled (port 0). A positive port prints tcp: enabled and bind: 127.0.0.1:PORT. See the CLI reference for launcher modes.

Gaps

Use the matching release source and smoke scripts for the released API, and development protocol §7 for bounded UI sampling. Older example README/design notes may describe obsolete framing, permissions, or timeout behavior.

Examples · API declarations

Examples

These sources come from the official examples repository and can be copied or downloaded. Run them with a local Xu SDK in the complete project; network, database, and desktop examples require the corresponding services or assets.

16_ui_webview/xacp_screen/main.xu

Required SDK: Xu 0.10.13-dev.1 · Complete project · Download source · events.xu

XuLocal SDK example
@main

#ui
#ui/widgets
#xacp
#errors

demo #"github.com/xulang-org/examples/ui_demo"

struct Model{
    label_id int
    count int
}

fn (m $&Model) layout(s $&widgets.Screen) int {
    s.place(m.label_id, 32.0, 36.0, 540.0, 44.0) or >>
    << 0
}

fn inspect_screen(s $&widgets.Screen) int {
    $session := xacp.open_session()
    // The in-process adapter follows the current session lifecycle too.
    // This token belongs only to this local demonstration; no listener is opened.
    permissions := xacp.PERM_UI_READ | xacp.PERM_UI_MUTATE
    limits := xacp.default_limits()
    $nonces := xacp.new_nonce_registry(8, true)
    hello := xacp.parse_frame("id: !i 1\nop: xacp.hello\nargs:\n  ver: !ver 1.0.0\n  nonce: local-screen-demo\n  token: local-screen-demo\n  permissions: !i " + str(permissions) + "\n") or(err) {
        xacp.close_session($&session)
        >> err
    }
    opened := xacp.dispatch_with_token($&session, &hello, &limits, "local-screen-demo", $&nonces)
    if !opened.ok{
        xacp.close_session($&session)
        >> errors.new("xacp_screen: " + opened.err_msg)
    }
    tree := xacp.ui_tree(& * s, $&session, 2, false, 0, 32, &limits) or(err) {
        xacp.close_session($&session)
        >> err
    }
    println("XACP ui.tree: " + str(tree.nodes.len) + " visible nodes")
    for node in tree.nodes{
        println("  #" + str(node.id) + " kind=" + str(node.kind) + " " + node.text)
    }

    $snapshot := xacp.ui_screenshot(& * s, $&session, 3, 1.0, &limits) or(err) {
        xacp.close_session($&session)
        >> err
    }
    println("XACP ui.screenshot: " + str(snapshot.pixel_width) + "x" + str(snapshot.pixel_height) + " pixels")
    snapshot.dispose() or(err) {
        xacp.close_session($&session)
        >> err
    }

    _ := xacp.ui_act(& * s, $&session, 2, 4, "focus", "", false, &limits) or(err) {
        xacp.close_session($&session)
        >> err
    }
    xacp.close_session($&session)
    << 0
}

fn scene(events chan ui.Event) int {
    ready := demo.ready(events) or >>
    if ready.kind == ui.EV_EXIT{ << 0}
    $screen := widgets.screen(&ready) or >>
    screen.resize(640.0, 180.0) or >>
    label_id := screen.label("XACP Screen adapter", 22.0, false) or >>
    button_id := screen.button("Activate locally or through ui.act") or >>
    screen.place(label_id, 32.0, 36.0, 540.0, 44.0) or >>
    screen.place(button_id, 32.0, 96.0, 360.0, 40.0) or >>
    inspect_screen($&screen) or(err) {
        screen.dispose()
        >> err
    }
    $model := Model{label_id: label_id, count: 0}
    $actions := widgets.action_dispatcher(&model, &screen)
    actions.on(button_id, widgets.ACTION_ACTIVATE, activate) or >>
    actions.set_fallback(global_key)
    << widgets.run_screen_actions($&screen, events, $&model, layout_action, &actions) or >>
}

fn worker(events chan ui.Event) {
    scene(events) or(err) {demo.fail(err.msg())
        << }
}

fn launch() int {
    $app := demo.app("Xu / XACP Screen adapter", 640, 180) or >>
    xu worker(app.event_ch)
    << app.run() or >>
}

fn main() int {
    << launch() or(err) {eprintln(err.msg())
        << 1}
}

API declarations

const MAX_FRAME_BYTES

XuAPI
pub const MAX_FRAME_BYTES = 1048576

Purpose

Constant MAX_FRAME_BYTES, defining protocol or algorithm parameters.

const MAX_STRING_BYTES

XuAPI
pub const MAX_STRING_BYTES = 65536

Purpose

Constant MAX_STRING_BYTES, defining protocol or algorithm parameters.

const MAX_FIELDS

XuAPI
pub const MAX_FIELDS = 64

Purpose

Constant MAX_FIELDS, defining protocol or algorithm parameters.

const MAX_TABLE_ROWS

XuAPI
pub const MAX_TABLE_ROWS = 10000

Purpose

Constant MAX_TABLE_ROWS, defining protocol or algorithm parameters.

const MAX_NODE_ID

XuAPI
pub const MAX_NODE_ID = 16777215

Purpose

Constant MAX_NODE_ID, defining protocol or algorithm parameters.

const DEFAULT_REQUEST_TIMEOUT_MS

XuAPI
pub const DEFAULT_REQUEST_TIMEOUT_MS = 5000

Purpose

Constant DEFAULT_REQUEST_TIMEOUT_MS, defining protocol or algorithm parameters.

const MAX_REQUEST_TIMEOUT_MS

XuAPI
pub const MAX_REQUEST_TIMEOUT_MS = 600000

Purpose

Constant MAX_REQUEST_TIMEOUT_MS, defining protocol or algorithm parameters.

const DEFAULT_WRITE_TIMEOUT_MS

XuAPI
pub const DEFAULT_WRITE_TIMEOUT_MS = 10000

Purpose

Constant DEFAULT_WRITE_TIMEOUT_MS, defining protocol or algorithm parameters.

const MAX_WRITE_TIMEOUT_MS

XuAPI
pub const MAX_WRITE_TIMEOUT_MS = 600000

Purpose

Constant MAX_WRITE_TIMEOUT_MS, defining protocol or algorithm parameters.

const DEFAULT_HELLO_TIMEOUT_MS

XuAPI
pub const DEFAULT_HELLO_TIMEOUT_MS = 5000

Purpose

Constant DEFAULT_HELLO_TIMEOUT_MS, defining protocol or algorithm parameters.

const MAX_HELLO_TIMEOUT_MS

XuAPI
pub const MAX_HELLO_TIMEOUT_MS = 600000

Purpose

Constant MAX_HELLO_TIMEOUT_MS, defining protocol or algorithm parameters.

const DEFAULT_IDLE_TIMEOUT_MS

XuAPI
pub const DEFAULT_IDLE_TIMEOUT_MS = 60000

Purpose

Constant DEFAULT_IDLE_TIMEOUT_MS, defining protocol or algorithm parameters.

const MIN_IDLE_TIMEOUT_MS

XuAPI
pub const MIN_IDLE_TIMEOUT_MS = 1000

Purpose

Constant MIN_IDLE_TIMEOUT_MS, defining protocol or algorithm parameters.

const MAX_IDLE_TIMEOUT_MS

XuAPI
pub const MAX_IDLE_TIMEOUT_MS = 3600000

Purpose

Constant MAX_IDLE_TIMEOUT_MS, defining protocol or algorithm parameters.

const DEFAULT_NONCE_CACHE

XuAPI
pub const DEFAULT_NONCE_CACHE = 1024

Purpose

Constant DEFAULT_NONCE_CACHE, defining protocol or algorithm parameters.

const MAX_NONCE_CACHE

XuAPI
pub const MAX_NONCE_CACHE = 65536

Purpose

Constant MAX_NONCE_CACHE, defining protocol or algorithm parameters.

const STATE_NEW

XuAPI
pub const STATE_NEW = 0

Purpose

Constant STATE_NEW, defining protocol or algorithm parameters.

const STATE_OPEN

XuAPI
pub const STATE_OPEN = 1

Purpose

Constant STATE_OPEN, defining protocol or algorithm parameters.

const STATE_CLOSED

XuAPI
pub const STATE_CLOSED = 2

Purpose

Constant STATE_CLOSED, defining protocol or algorithm parameters.

const PERM_NONE

XuAPI
pub const PERM_NONE = 0

Purpose

Constant PERM_NONE, defining protocol or algorithm parameters.

const PERM_INFO

XuAPI
pub const PERM_INFO = 1

Purpose

Constant PERM_INFO, defining protocol or algorithm parameters.

const PERM_PROCESS

XuAPI
pub const PERM_PROCESS = 2

Purpose

Constant PERM_PROCESS, defining protocol or algorithm parameters.

const PERM_UI_READ

XuAPI
pub const PERM_UI_READ = 4

Purpose

Constant PERM_UI_READ, defining protocol or algorithm parameters.

See usage example

const PERM_UI_MUTATE

XuAPI
pub const PERM_UI_MUTATE = 8

Purpose

Constant PERM_UI_MUTATE, defining protocol or algorithm parameters.

See usage example

const PERM_UI_RAW

XuAPI
pub const PERM_UI_RAW = 16

Purpose

Constant PERM_UI_RAW, defining protocol or algorithm parameters.

const PERM_ALL

XuAPI
pub const PERM_ALL = 31

Purpose

Constant PERM_ALL, defining protocol or algorithm parameters.

struct Limits

XuAPI
pub struct Limits {
    pub max_frame_bytes int
    pub max_string_bytes int
    pub max_fields int
    pub max_table_rows int
    pub max_node_id int
    pub request_timeout_ms int
    pub write_timeout_ms int
    pub hello_timeout_ms int
    pub idle_timeout_ms int
}

Purpose

Structure encapsulating max_frame_bytes, max_string_bytes, max_fields, max_table_rows, max_node_id.

Public fields

max_frame_bytes int
field (int)
max_string_bytes int
field (int)
max_fields int
field (int)
max_table_rows int
field (int)
max_node_id int
field (int)
request_timeout_ms int
field (int)
write_timeout_ms int
field (int)
hello_timeout_ms int
field (int)
idle_timeout_ms int
field (int)

struct Session

XuAPI
pub struct Session {
    pub state int
    pub generation int
    pub next_id int
    pub active_id int
    pub active_generation int
    pub permissions int
    pub nonce string
    pub bytes_in int
    pub bytes_out int
}

Purpose

Structure encapsulating state, generation, next_id, active_id, active_generation.

Public fields

state int
field (int)
generation int
field (int)
next_id int
field (int)
active_id int
field (int)
active_generation int
field (int)
permissions int
field (int)
nonce string
field (string)
bytes_in int
field (int)
bytes_out int
field (int)

struct NonceRegistry

XuAPI
pub struct NonceRegistry {

}

Purpose

The host owns this bounded FIFO across sessions. Sequential listeners borrow it exclusively while negotiating; concurrent hosts must serialize that borrow.

Public fields

This type has no public fields.

new_nonce_registry

XuAPI
pub fn new_nonce_registry(capacity int, enabled bool) NonceRegistry

Purpose

Invalid capacities use the default. Disabled registries retain no nonces.

Parameters

capacity int
capacity (int)
enabled bool
enabled (bool)

Returns

NonceRegistry — a value of this type

See usage example

struct Request

XuAPI
pub struct Request {
    pub id int
    pub op string
    pub args int
}

Purpose

Structure encapsulating id, op, args.

Public fields

id int
field (int)
op string
field (string)
args int
variadic arguments

struct Outcome

XuAPI
pub struct Outcome {
    pub ok bool
    pub request_id int
    pub err_code string
    pub err_msg string
}

Purpose

Structure encapsulating ok, request_id, err_code, err_msg.

Public fields

ok bool
field (bool)
request_id int
field (int)
err_code string
field (string)
err_msg string
field (string)

default_limits

XuAPI
pub fn default_limits() Limits

Purpose

Default limits.

Parameters

No arguments are required.

Returns

Limits — a value of this type

See usage example

request_timeout_from_env

XuAPI
pub fn request_timeout_from_env() int

Purpose

Read once when the control server initializes its limits. Only ASCII decimal 1..600000 is accepted; invalid values silently keep the default deadline.

Parameters

No arguments are required.

Returns

int — a value of this type

write_timeout_from_env

XuAPI
pub fn write_timeout_from_env() int

Purpose

write_timeout_from_env accepts ASCII decimal 1..600000, otherwise the default.

Parameters

No arguments are required.

Returns

int — a value of this type

hello_timeout_from_env

XuAPI
pub fn hello_timeout_from_env() int

Purpose

hello_timeout_from_env accepts ASCII decimal 1..600000, otherwise the default.

Parameters

No arguments are required.

Returns

int — a value of this type

idle_timeout_from_env

XuAPI
pub fn idle_timeout_from_env() int

Purpose

idle_timeout_from_env accepts 1000..3600000 or 0 to disable idle expiry. Empty, malformed, out-of-range and overflowing input keeps the default.

Parameters

No arguments are required.

Returns

int — a value of this type

nonce_cache_from_env

XuAPI
pub fn nonce_cache_from_env() int

Purpose

Hosts read nonce policy once when starting a listener/control loop.

Parameters

No arguments are required.

Returns

int — a value of this type

nonce_replay_from_env

XuAPI
pub fn nonce_replay_from_env() bool

Purpose

Nonce replay from env.

Parameters

No arguments are required.

Returns

bool — true or false

open_session

XuAPI
pub fn open_session() Session

Purpose

Open session.

Parameters

No arguments are required.

Returns

Session — a value of this type

See usage example

close_session

XuAPI
pub fn close_session(s $&Session)

Purpose

Close session.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)

Returns

This call does not return a value.

See usage example

cancel_request

XuAPI
pub fn cancel_request(s $&Session)

Purpose

Cancel request.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)

Returns

This call does not return a value.

set_permissions

XuAPI
pub fn set_permissions(s $&Session, permissions int) bool

Purpose

Permission grants are explicit host policy. Unknown bits are rejected and permissions cannot be changed after a session has begun serving requests.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
permissions int
permissions (int)

Returns

bool — true or false

development_permissions

XuAPI
pub fn development_permissions() int

Purpose

Development hosts may opt into the complete permission set explicitly. This is policy only; schema, byte, window, and lifecycle checks still apply.

Parameters

No arguments are required.

Returns

int — a value of this type

enable_development

XuAPI
pub fn enable_development(s $&Session) bool

Purpose

Enable development.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)

Returns

bool — true or false

parse_frame

XuAPI
pub fn parse_frame(src string) xun.Doc

Purpose

Parse the plain XUN body of one XACP/1 frame. The transport has already stripped the XACP/1\n<N>\n length prefix and read exactly N bytes; pass only the body. Throws for an empty body, a body above MAX_FRAME_BYTES, or invalid XUN.

Parameters

src string
plain XUN body after transport decoding, without the length prefix

Returns

parsed XUN document; validate_request checks the request schema separately

See usage example

request_id_hint

XuAPI
pub fn request_id_hint(d &xun.Doc) int

Purpose

request_id_hint returns a top-level id: !i N if one parses, otherwise 0, so schema errors can still echo the caller's id.

Parameters

d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)

Returns

int — a value of this type

validate_request

XuAPI
pub fn validate_request(d &xun.Doc, l &Limits) Request

Purpose

validate_request enforces the fixed top-level schema and rejects every operation that has not been explicitly added to this package's schema. Throws on failure; handle the error or propagate it to the caller.

Parameters

d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

Request — a value of this type

authorized

XuAPI
pub fn authorized(s $&Session, r &Request) bool

Purpose

Execute authorized.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
r &Request
rune (Unicode code point) (read-only borrow; caller keeps the original; type &Request)

Returns

bool — true or false

begin_request

XuAPI
pub fn begin_request(s $&Session, r &Request) Outcome

Purpose

Begin request.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
r &Request
rune (Unicode code point) (read-only borrow; caller keeps the original; type &Request)

Returns

Outcome — a value of this type

finish_request

XuAPI
pub fn finish_request(s $&Session, id int) Outcome

Purpose

Finish request.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
id int
id (int)

Returns

Outcome — a value of this type

consume_input

XuAPI
pub fn consume_input(s $&Session, n int, l &Limits) bool

Purpose

Consume input.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
n int
count, length, or limit (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

bool — true or false

consume_output

XuAPI
pub fn consume_output(s $&Session, n int, l &Limits) bool

Purpose

Consume output.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
n int
count, length, or limit (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

bool — true or false

check_window

XuAPI
pub fn check_window(start int, count int, total int, l &Limits) bool

Purpose

Check window.

Parameters

start int
start (int)
count int
count (int)
total int
total (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

bool — true or false

check_node

XuAPI
pub fn check_node(node int, l &Limits) bool

Purpose

Check node.

Parameters

node int
node (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

bool — true or false

negotiate_hello

XuAPI
pub fn negotiate_hello(s $&Session, d &xun.Doc, r &Request, expected_token string, nonces $&NonceRegistry) Outcome

Purpose

negotiate_hello consumes a schema-validated, reserved hello. The host supplies its expected token and shared registry; RAW additionally requires host opt-in. A client token alone never grants more than INFO when the host has no token.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
r &Request
rune (Unicode code point) (read-only borrow; caller keeps the original; type &Request)
expected_token string
expected_token (string)
nonces $&NonceRegistry
nonces (exclusive borrow; may modify the original; type $&NonceRegistry)

Returns

Outcome — a value of this type

dispatch

XuAPI
pub fn dispatch(s $&Session, d &xun.Doc, l &Limits, nonces $&NonceRegistry) Outcome

Purpose

dispatch performs only the safe core lifecycle with the default INFO policy. Data-bearing adapters implement operations after the same checks.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)
nonces $&NonceRegistry
nonces (exclusive borrow; may modify the original; type $&NonceRegistry)

Returns

Outcome — a value of this type

dispatch_with_token

XuAPI
pub fn dispatch_with_token(s $&Session, d &xun.Doc, l &Limits, expected_token string, nonces $&NonceRegistry) Outcome

Purpose

Hosts with an explicit authentication policy pass the expected token here.

Parameters

s $&Session
s (exclusive borrow; may modify the original; type $&Session)
d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)
expected_token string
expected_token (string)
nonces $&NonceRegistry
nonces (exclusive borrow; may modify the original; type $&NonceRegistry)

Returns

Outcome — a value of this type

See usage example

struct ControlReply

XuAPI
pub struct ControlReply {
    pub outcome Outcome
    pub data string
}

Purpose

Only owning strings, scalars and channel handles cross the control coroutine.

Public fields

outcome Outcome
field (Outcome)
data string
data

struct ControlJob

XuAPI
pub struct ControlJob {
    pub id int
    pub op string
    pub body string
    pub permissions int
    pub generation int
    pub started int
    pub timeout_ms int
    pub reply chan ControlReply
}

Purpose

Structure encapsulating id, op, body, permissions, generation.

Public fields

id int
field (int)
op string
field (string)
body string
body
permissions int
field (int)
generation int
field (int)
started int
field (int)
timeout_ms int
field (int)
reply chan ControlReply
field (channel; type chan ControlReply)

struct ScreenControl

XuAPI
pub struct ScreenControl {
    pub done chan int
}

Purpose

One attachment per process, with one registered Screen. Keep this handle in the Screen-owning coroutine. The state token serializes registration/enqueue the one-slot mailbox bounds pending work. No Screen reference is retained.

Public fields

done chan int
field (channel; type chan int)

attach_stdio

XuAPI
pub fn attach_stdio() ScreenControl

Purpose

Explicit attachment: business main continues; stdin/stdout carry XACP. Prefer stderr for logs on this shared transport. Both streams are captured. done receives the server exit status at EOF.

Parameters

No arguments are required.

Returns

ScreenControl — a value of this type

attach_tcp

XuAPI
pub fn attach_tcp(port int) ScreenControl

Purpose

Loopback TCP uses the same sequential-peer and authentication policy as exclusive TCP. The caller must use a valid port and keep polling until exit. Throws on failure; handle the error or propagate it to the caller.

Parameters

port int
port (int)

Returns

ScreenControl — a value of this type

register_screen

XuAPI
pub fn register_screen(control $&ScreenControl,s &widgets.Screen) int

Purpose

Registration borrows only during this call. Duplicate registration is rejected; unregister before registering another Screen. Close/dispose sends a channel notification so the control side also invalidates idle screens. Throws on failure; handle the error or propagate it to the caller.

Parameters

control $&ScreenControl
control (exclusive borrow; may modify the original; type $&ScreenControl)
s &widgets.Screen
s (read-only borrow; caller keeps the original; type &widgets.Screen)

Returns

int — a value of this type

unregister_screen

XuAPI
pub fn unregister_screen(control $&ScreenControl)

Purpose

The UI owner must unregister before abandoning the poll loop. A queued job receives stale_window. New requests see not_implemented without needing poll.

Parameters

control $&ScreenControl
control (exclusive borrow; may modify the original; type $&ScreenControl)

Returns

This call does not return a value.

poll

XuAPI
pub fn poll(control $&ScreenControl,s $&widgets.Screen) bool

Purpose

Nonblocking: service at most one request between UI event iterations. Never call a blocking UI wait while control work needs polling. A registered owner that stops polling gets request_timeout after the configured deadline. Work already executing is not interrupted; its late reply is buffered and discarded.

Parameters

control $&ScreenControl
control (exclusive borrow; may modify the original; type $&ScreenControl)
s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)

Returns

bool — true or false

struct RecordBuffer

XuAPI
pub struct RecordBuffer {

}

Purpose

StreamWriter with all-or-error appends. Neither a failed write nor a caller-supplied large max_records can grow the retained payload past limit.

Public fields

This type has no public fields.

record_buffer

XuAPI
pub fn record_buffer(max_bytes int) RecordBuffer

Purpose

Record buffer. Throws on failure; handle the error or propagate it to the caller.

Parameters

max_bytes int
max_bytes (int)

Returns

RecordBuffer — a value of this type

($&RecordBuffer) write_str

XuAPI
pub fn (b $&RecordBuffer) write_str(data string) int

Purpose

Operation on $&RecordBuffer: write a string. Throws on failure; handle the error or propagate it to the caller.

Parameters

b $&RecordBuffer
The RecordBuffer instance used by this call (exclusive borrow).
data string
data (string)

Returns

int — a value of this type

(&RecordBuffer) text

XuAPI
pub fn (b &RecordBuffer) text() string

Purpose

Operation on &RecordBuffer: return the current text.

Parameters

b &RecordBuffer
The RecordBuffer instance used by this call (borrow).

Returns

string — result string

const MAX_SCREENSHOT_BYTES

XuAPI
pub const MAX_SCREENSHOT_BYTES = 33554432

Purpose

Constant MAX_SCREENSHOT_BYTES, defining protocol or algorithm parameters.

screenshot_dir

XuAPI
pub fn screenshot_dir() string

Purpose

Absolute directory for the host only; the wire always returns a basename. The POSIX native UI host creates/validates private directories on first write. Throws on failure; handle the error or propagate it to the caller.

Parameters

No arguments are required.

Returns

string — result string

program_preflight

XuAPI
pub fn program_preflight(port int)

Purpose

Discover the compiled capabilities before dispatching to an explicit control mode.

Parameters

port int
port (int)

Returns

This call does not return a value.

stdio_preflight

XuAPI
pub fn stdio_preflight(port int)

Purpose

Explicit control modes skip business main; the first control flag wins. Ordinary invocations never listen or read control stdin. The -- boundary protects application arguments.

Parameters

port int
port (int)

Returns

This call does not return a value.

const MAX_ERROR_MSG_BYTES

XuAPI
pub const MAX_ERROR_MSG_BYTES = 256

Purpose

Constant MAX_ERROR_MSG_BYTES, defining protocol or algorithm parameters.

serve_stdio

XuAPI
pub fn serve_stdio() int

Purpose

Chunked reads and an amortized builder bound memory and copying. EOF and fatal frame/schema/auth errors terminate the session; complete frames may share a read. Throws on failure; handle the error or propagate it to the caller.

Parameters

No arguments are required.

Returns

int — a value of this type

serve_tcp

XuAPI
pub fn serve_tcp(port int) int

Purpose

Explicit exclusive control mode; loopback only, sequential connections. A malformed/disconnected peer ends its session, not the listener. Throws on failure; handle the error or propagate it to the caller.

Parameters

port int
port (int)

Returns

int — a value of this type

const MAX_UI_EVENTS

XuAPI
pub const MAX_UI_EVENTS = 512

Purpose

ScreenAdapter is the typed bridge between the transport-neutral XACP core and a live widgets.Screen. The Screen still owns all native resources; this package only borrows it for the duration of each checked operation.

struct Recorder

XuAPI
pub struct Recorder {
    pub mode string
    pub max_bytes int
    pub bytes int
    pub sequence int
    pub closed bool
    pub request_id int
    pub session_generation int
}

Purpose

Structure encapsulating mode, max_bytes, bytes, sequence, closed.

Public fields

mode string
mode
max_bytes int
field (int)
bytes int
field (int)
sequence int
field (int)
closed bool
field (bool)
request_id int
field (int)
session_generation int
field (int)

new_recorder

XuAPI
pub fn new_recorder(mode string,max_bytes int,l &Limits) Recorder

Purpose

Construct recorder. Throws on failure; handle the error or propagate it to the caller.

Parameters

mode string
mode (string)
max_bytes int
max_bytes (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

Recorder — a value of this type

($&Recorder) close

XuAPI
pub fn (r $&Recorder) close()

Purpose

Operation on $&Recorder: close the resource.

Parameters

r $&Recorder
The Recorder instance used by this call (exclusive borrow).

Returns

This call does not return a value.

(&Recorder) is_open

XuAPI
pub fn (r &Recorder) is_open() bool

Purpose

Operation on &Recorder: whether it is open.

Parameters

r &Recorder
The Recorder instance used by this call (borrow).

Returns

bool — true or false

write_record

XuAPI
pub fn write_record#W:StreamWriter(r $&Recorder,sink $&W,kind string,data string) int

Purpose

write_record is deliberately streaming: no record is retained after the sink accepts it. The length prefix lets a consumer reject truncation without parsing untrusted payload bytes. A failed sink write does not advance the recorder's accounting or sequence. Throws on failure; handle the error or propagate it to the caller.

Parameters

r $&Recorder
rune (Unicode code point) (exclusive borrow; may modify the original; type $&Recorder)
sink $&W
sink (exclusive borrow; may modify the original; type $&W)
kind string
kind tag (string)
data string
data (string)

Returns

int — a value of this type

input_record

XuAPI
pub fn input_record(event &ui.InputEvent) string

Purpose

Input record.

Parameters

event &ui.InputEvent
event (read-only borrow; caller keeps the original; type &ui.InputEvent)

Returns

string — result string

surface_record

XuAPI
pub fn surface_record(surface &draw.Surface) string

Purpose

Surface record.

Parameters

surface &draw.Surface
surface (read-only borrow; caller keeps the original; type &draw.Surface)

Returns

string — result string

struct TreeWindow

XuAPI
pub struct TreeWindow {
    pub start int
    pub total int
    pub nodes []widgets.ScreenNodeInfo
}

Purpose

Structure encapsulating start, total, nodes.

Public fields

start int
field (int)
total int
field (int)
nodes []widgets.ScreenNodeInfo
field ([]widgets.ScreenNodeInfo)

screen_tree

XuAPI
pub fn screen_tree(s $&widgets.Screen,include_hidden bool,start int,max_rows int,l &Limits) TreeWindow

Purpose

Read-only tree window. The returned nodes are copies and remain valid after the caller releases the Screen borrow. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
include_hidden bool
include_hidden (bool)
start int
start (int)
max_rows int
max_rows (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

TreeWindow — a value of this type

screen_screenshot

XuAPI
pub fn screen_screenshot(s $&widgets.Screen,scale f64) draw.Surface

Purpose

The Surface is a native resource with explicit ownership. The caller must dispose it, including error and cancellation paths; no byte copy is staged in the adapter. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
scale f64
scale (f64)

Returns

draw.Surface — a value of this type

screen_screenshot_node

XuAPI
pub fn screen_screenshot_node(s $&widgets.Screen,node int,scale f64,l &Limits) draw.Surface

Purpose

Screen screenshot node. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
node int
node (int)
scale f64
scale (f64)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

draw.Surface — a value of this type

screen_input

XuAPI
pub fn screen_input(s $&widgets.Screen,events &[]ui.InputEvent,l &Limits) []widgets.Action

Purpose

Screen input. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
events &[]ui.InputEvent
events (read-only borrow; caller keeps the original; type &[]ui.InputEvent)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

[]widgets.Action — slice result

screen_input_request

XuAPI
pub fn screen_input_request(s $&widgets.Screen,d &xun.Doc,args int,l &Limits) []widgets.Action

Purpose

Screen input request. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
args int
variadic arguments (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

[]widgets.Action — slice result

screen_act

XuAPI
pub fn screen_act(s $&widgets.Screen,id int,act string,text string,checked bool,l &Limits) []widgets.Action

Purpose

Screen act. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
id int
id (int)
act string
act (string)
text string
text (string)
checked bool
checked (bool)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

[]widgets.Action — slice result

start_recorder

XuAPI
pub fn start_recorder(session $&Session,id int,mode string,max_bytes int,l &Limits) Recorder

Purpose

Start recorder. Throws on failure; handle the error or propagate it to the caller.

Parameters

session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
mode string
mode (string)
max_bytes int
max_bytes (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

Recorder — a value of this type

finish_recorder

XuAPI
pub fn finish_recorder(session $&Session,r $&Recorder) int

Purpose

Finish recorder. Throws on failure; handle the error or propagate it to the caller.

Parameters

session $&Session
session (exclusive borrow; may modify the original; type $&Session)
r $&Recorder
rune (Unicode code point) (exclusive borrow; may modify the original; type $&Recorder)

Returns

int — a value of this type

abort_recorder

XuAPI
pub fn abort_recorder(session $&Session,r $&Recorder)

Purpose

Abort recorder.

Parameters

session $&Session
session (exclusive borrow; may modify the original; type $&Session)
r $&Recorder
rune (Unicode code point) (exclusive borrow; may modify the original; type $&Recorder)

Returns

This call does not return a value.

ui_tree

XuAPI
pub fn ui_tree(s $&widgets.Screen,session $&Session,id int,include_hidden bool,start int,max_rows int,l &Limits) TreeWindow

Purpose

Permission-bearing entry points. Every operation reserves a monotonic request id and releases it on both success and adapter failure. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
include_hidden bool
include_hidden (bool)
start int
start (int)
max_rows int
max_rows (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

TreeWindow — a value of this type

See usage example

ui_screenshot

XuAPI
pub fn ui_screenshot(s $&widgets.Screen,session $&Session,id int,scale f64,l &Limits) draw.Surface

Purpose

Ui screenshot. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
scale f64
scale (f64)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

draw.Surface — a value of this type

See usage example

ui_screenshot_node

XuAPI
pub fn ui_screenshot_node(s $&widgets.Screen,session $&Session,id int,node int,scale f64,l &Limits) draw.Surface

Purpose

Ui screenshot node. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
node int
node (int)
scale f64
scale (f64)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

draw.Surface — a value of this type

ui_input

XuAPI
pub fn ui_input(s $&widgets.Screen,session $&Session,id int,events &[]ui.InputEvent,l &Limits) []widgets.Action

Purpose

Ui input. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
events &[]ui.InputEvent
events (read-only borrow; caller keeps the original; type &[]ui.InputEvent)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

[]widgets.Action — slice result

ui_input_request

XuAPI
pub fn ui_input_request(s $&widgets.Screen,session $&Session,id int,d &xun.Doc,args int,l &Limits) []widgets.Action

Purpose

Ui input request. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
args int
variadic arguments (int)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

[]widgets.Action — slice result

ui_act

XuAPI
pub fn ui_act(s $&widgets.Screen,session $&Session,id int,request_id int,act string,text string,checked bool,l &Limits) []widgets.Action

Purpose

Ui act. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
id int
id (int)
request_id int
request_id (int)
act string
act (string)
text string
text (string)
checked bool
checked (bool)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)

Returns

[]widgets.Action — slice result

See usage example

dispatch_screen

XuAPI
pub fn dispatch_screen(s $&widgets.Screen,session $&Session,d &xun.Doc,l &Limits,nonces $&NonceRegistry) ControlReply

Purpose

dispatch_screen executes the schema-approved UI operations against the registered Screen and serializes every successful result before releasing the borrow. Native Surfaces are disposed before the owning PNG reply crosses the mailbox; only the authoritative session can export a screenshot file. Throws on failure; handle the error or propagate it to the caller.

Parameters

s $&widgets.Screen
s (exclusive borrow; may modify the original; type $&widgets.Screen)
session $&Session
session (exclusive borrow; may modify the original; type $&Session)
d &xun.Doc
d (read-only borrow; caller keeps the original; type &xun.Doc)
l &Limits
l (read-only borrow; caller keeps the original; type &Limits)
nonces $&NonceRegistry
nonces (exclusive borrow; may modify the original; type $&NonceRegistry)

Returns

ControlReply — a value of this type