Module pairing 

The pairing contract on disk: identity resolution, the pair record, the claim_file primitive and the liveness sentinels (spec “Pairing contract”; files are pair.<pair-id>.* in the ctl home).

Structs

Identity

Who this server is paired with. source is File only when a record was read and parsed.

Record

pair.<id>.json.

Enums

IdentitySource

Functions

apply_identity

Write the resolved identity into the environment snapshot and, for a File identity, the record’s server_url into the settings: settings.server_url = identity.server_url (a null record means the background service, exactly as an empty OPENCODE_CTL_SERVER does) with the source Env, overriding a user-file value. Env and None identities (a missing or unparsable record yields None) leave the settings untouched. A record URL carrying userinfo is ignored: the settings keep their current value and source, and env.server is cleared.

apply_record_server

resume talks to the server its pair was made for: the record’s server_url is applied to the settings exactly as apply_identity applies a File identity (a null value is the background service, a URL with userinfo is ignored). A missing or unreadable record changes nothing; resume itself reports that.

claim_file

Create path with content only if it does not exist, complete from the first moment it is visible (temp + hard_link). Ok(false) when path already exists.

delete_pair_files

Remove every file of one pair (pair.<id>.*, including temp files and the lock).

ensure_dir 🔒

has_userinfo 🔒

invalid_pair 🔒

list_records

Every parsable pair.<id>.json, keyed on the FILE NAME’s id (see read_record); an unparsable one is logged and skipped.

lock_path 🔒

open_new 🔒

parse_record 🔒

read_record

Ok(None) for a missing or unparsable record (the latter logged); IO_ERROR for other read errors.

read_sentinel

An absent, empty or unparsable file reads as None.

record_ids

The valid pair ids named by pair.<id>.json FILE NAMES, sorted (whatever the file holds).

record_path

replace_file 🔒

Temp + rename over path.

resolve_identity

Env vars first; only OPENCODE_CTL_PAIR set means the record supplies the rest. Returns the identity and the startup warnings (logged by the caller). An invalid id leaves the server unpaired.

rewrite_record

Rewrite only generation and tab, under the pair’s lock, never lowering the generation.

temp_sibling 🔒

valid_pair_id

^[0-9a-f]{12}$.

write_record_new

write_sentinel

write_temp 🔒