Module plugin 

The SourcePlugin contract — what a source is, to the engine.

A plugin’s only job is to land raw material in the run directory the engine hands it; the curation agent is the universal adapter, so the engine never parses source payloads. Builtins implement the trait in-process; external plugins speak the same shapes over stdio RON (harness arrives with tap support).

Structs

AuthChallenge

An interactive sign-in challenge (device-code style): show the code, send the human to the URL, poll until done. The handle is an opaque continuation for auth_poll — the engine holds it server-side.

Context

What the engine hands a plugin for AUTH operations. Paths are engine-owned: plugins never invent storage locations.

Describe

What a plugin declares about itself.

FetchRequest

One fetch invocation (ADR 0001). The checkpoint is a READ-ONLY snapshot of the last successfully PUBLISHED run’s successor — plugins carry no writable durable state, so no crash before publication can suppress a future fetch.

FetchResult

A fetch’s result. The engine publishes the manifest atomically and only then treats next_checkpoint as the authoritative cursor.

Item

One PROVIDER item — a message, an event, a chat message, a recording session, a file version. Identity is source instance + kind + id (ADR 0001); run ids, filenames and bundle names are never identity. Serde defaults keep legacy aggregate manifests parseable.

Enums

AuthPollResult

AuthStatus

FetchStyle

How runs of this source are bounded.

PluginRequest

One request to a tap binary: <binary> --plugin <name> with this as RON on stdin, one PluginResponse as RON on stdout. Mirrors the schema protocol: a fresh process per call, no session state — checkpoints and ledgers are engine-owned, so plugins have nothing to keep alive.

PluginResponse

RunSpec

What the engine asks a fetch to do (matches the plugin’s declared style).

Constants

PROTOCOL

The plugin contract version this engine speaks (ADR 0001).

Traits

SourcePlugin

The contract (ADR 0001). Builtins implement it in-process; the stdio harness for external plugins wraps the same shapes.

Functions

tap_main

The whole main() of a tap binary: parse --plugin <name>, resolve it through the tap’s own table, serve one request. Progress goes to stderr (the harness forwards it to the host’s progress sink).

version_fingerprint

See Item::version_fingerprint — shared with engine projections that store the components rather than the item.