Layer 6 External Transport

Layer 6 — External Transport

Pluggable transport system for cross-device sync, keeping the core networking-free.

Transport Contract

A transport is a struct of two nullable function pointers:

typedef sv_xport_status_t (*sv_xport_push_fn)(
    const sv_entry_info_t *entry,
    const char *magazine_slot_path,   /* read-only source — never the live path */
    void *user_ctx
);

typedef sv_xport_status_t (*sv_xport_pull_fn)(
    const sv_id_t reg_id,
    sv_entry_info_t *out_entry,
    char *out_dest_buf, size_t out_dest_buf_len,
    void *user_ctx
);

Transports can be write-only, read-only, or both. The user_ctx pointer allows transports to carry their own state (API keys, connection handles, etc.).

Push External

sv_push_external(entry_id, transport) sends one specific magazine entry out through the transport. The transport receives:

• Entry metadata (sv_entry_info_t)
• The magazine slot path (read-only source — never the live path)
• The user context

Pull External

sv_pull_external(reg_id, transport, pull_opts) fetches a remote save into a new local magazine entry — it never writes directly to the live path.

The two-step model:

1. pull_external — fetch remote save into magazine (creates new entry, computes hash, triggers retention)
2. pull — promote magazine entry to live save

This mirrors sv_save()'s mechanics and reuses the same conflict-handling struct as local pull() — one conflict model for the whole library.

Error Handling

Transport errors are structured without the core knowing anything about the underlying protocol:

Error	Meaning
SV_XPORT_OK	Success
SV_XPORT_ERR_IO	I/O error
SV_XPORT_ERR_AUTH	Authentication failure
SV_XPORT_ERR_NOT_FOUND	Remote entry not found
SV_XPORT_ERR_CONFLICT	Remote conflict
SV_XPORT_ERR_OTHER	Unknown error

Supported Transports (future)

The transport contract is protocol-agnostic. Any of these can be implemented externally:

• USB/file copy
• HTTP/HTTPS
• LAN/mDNS
• Terminal/serial
• Custom protocols

---

See also: Architecture-Overview | Layer-4-Local-Save-and-Pull | API-Reference