dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/drivers/decision_stop.py

@@ -0,0 +1,98 @@
+"""dos.drivers.decision_stop — a reference loop-STOP policy (a `dos.stop_policy` occupant).
+
+The kernel scout's default is "an open operator decision is evidence-only, never a
+STOP" (the 2026-06-03 directive). That is right for most decisions — a WEDGE or an
+open soak gate blocks *future* work but wastes nothing while it waits, so halting
+the whole loop on it is over-reach. But one decision class is different: a
+`LIVENESS` row is an `OP_HALT` proposal — a run a watchdog judged SPINNING/hung
+RIGHT NOW, actively burning budget. For a host that wants its loop to halt rather
+than keep launching work alongside a doomed run, "stop on a LIVENESS decision" is a
+legitimate policy.
+
+This driver is the reference `dos.stop_policy.StopPolicy` occupant that encodes
+exactly that, configurably:
+
+  * `DecisionClassStopPolicy(stop_classes=("LIVENESS",))` — reads the live
+    `dos.decisions` HUMAN queue and returns `StopVerdict.stop(...)` iff a pending
+    decision's `kind` is in `stop_classes`; otherwise `StopVerdict.defer()` (fall
+    through to the kernel's evidence-only default — WEDGE/soak/arbiter-refuse only
+    surface). The default `stop_classes` is `("LIVENESS",)` — the one urgent class.
+
+It lives in a **driver**, not the kernel, because it does I/O (reads the decision
+queue) and encodes host policy (which classes are halt-worthy) — the same reason a
+ruling judge or a model-backed overlap scorer lives here. The kernel seam
+(`dos.stop_policy`) holds only the Protocol + the fail-to-DEFER wrapper + the
+resource-floor AND; this is one concrete policy under it. Registered under the
+`dos.stop_policies` entry-point group so `resolve_stop_policy("decision-class")`
+returns it; a host opts in by naming it in `dos.toml [scout] stop_policy`.
+
+Safety: the policy reads the queue inside `decide`, and any fault there is caught
+by the kernel's `run_stop_policy` (fail-to-DEFER) — but we ALSO guard the read here
+so a torn/missing queue degrades to "no halt-worthy decision" (DEFER) with a clear
+reason, rather than relying solely on the wrapper. And whatever this returns, the
+kernel ANDs it under the `resource_blocked` floor, so this policy can only ever
+*add* a halt, never suppress the measured resource STOP.
+"""
+
+from __future__ import annotations
+
+from dos.stop_policy import StopVerdict
+
+# The decision classes this policy halts on, by default. LIVENESS = an OP_HALT
+# proposal: a run hung/spinning NOW, burning budget — the one class where letting
+# the loop keep launching work is worse than stopping. Everything else (WEDGE,
+# ARBITER_REFUSE, PREFLIGHT_REFUSE, SOAK_GATE) blocks future work but wastes nothing
+# waiting, so it stays evidence-only (DEFER → the kernel default surfaces it).
+_DEFAULT_STOP_CLASSES = ("LIVENESS",)
+
+
+class DecisionClassStopPolicy:
+    """STOP the loop iff a pending operator decision is of a configured urgent class.
+
+    The reference `dos.stop_policy.StopPolicy`. `stop_classes` is the set of
+    `dos.decisions.DecisionKind` values that warrant a halt (default
+    `("LIVENESS",)`). `decide` reads the live HUMAN decision queue for the active
+    workspace and returns STOP on the first match, else DEFER.
+    """
+
+    name = "decision-class"
+
+    def __init__(self, stop_classes: tuple[str, ...] = _DEFAULT_STOP_CLASSES) -> None:
+        # Normalize to an upper-cased set for a case-insensitive `kind` match.
+        self.stop_classes = frozenset(c.strip().upper() for c in stop_classes if c)
+
+    def decide(self, state: object, config: object) -> StopVerdict:
+        """Read the live HUMAN decision queue; STOP on an urgent-class row, else DEFER.
+
+        Guarded: a missing/torn queue (or an absent kernel decisions module) →
+        DEFER, never a spurious halt. The kernel's `run_stop_policy` would also
+        catch a raise, but degrading here gives a clearer reason and keeps the
+        policy honest on its own.
+        """
+        try:
+            from dos import config as _config
+            from dos import decisions as _decisions
+            cfg = config if config is not None else _config.active()
+            rows = _decisions.collect_decisions(cfg, resolver="HUMAN")
+        except Exception as e:
+            return StopVerdict.defer(
+                f"decision-class policy could not read the queue ({e!r}) — "
+                f"deferring (no halt)."
+            )
+        for d in rows:
+            kind = getattr(getattr(d, "kind", None), "value", "")
+            if str(kind).upper() in self.stop_classes:
+                lane = getattr(d, "lane", "") or "-"
+                text = getattr(d, "reason_text", "") or kind
+                return StopVerdict.stop(
+                    f"a {kind} decision is pending (lane {lane!r}): {text[:120]}. "
+                    f"Host policy halts the loop on this class — resolve it "
+                    f"(`dos decisions` / F9) before relaunching.",
+                    cause_key=f"stop_on_{str(kind).lower()}",
+                    evidence=(f"{kind} lane={lane}",
+                              f"stop_classes={sorted(self.stop_classes)}"),
+                )
+        return StopVerdict.defer(
+            f"no pending decision in the halt classes {sorted(self.stop_classes)} "
+            f"({len(rows)} HUMAN decision(s) pending, all evidence-only)."
+        )

dos/drivers/export_file.py

@@ -0,0 +1,173 @@
+"""dos.drivers.export_file — the append-to-a-file occupant of `dos.exporter` (docs/266).
+
+The first connector behind the verdict exporter, and the KEYSTONE one. Where the
+kernel seam (`dos.exporter`) is transport-agnostic and names no transport, THIS is
+where "append to a path" is allowed to be code — and it names no SPECIFIC vendor: it
+re-emits each `VerdictEvent` as one JSONL line to an operator-chosen path, so the one
+driver reaches *most* of the observability market for free. A JSONL stream at a path is
+the universal adapter — Datadog's agent, Vector, Fluent Bit, Promtail, Splunk's
+forwarder, and `logger(1)` all tail a file. It registers through the `dos.exporters`
+entry-point group, so `resolve_exporter("file")` finds it by name and no kernel module
+imports it.
+
+Why it ships in the core (no extra)
+===================================
+
+A file append needs only `pathlib` + `json` from the standard library. So this driver
+adds NO dependency and ships in the core install — a `pip install dos-kernel` can
+already drain its verdict journal to any log shipper. (The StatsD driver is also
+stdlib; only the OTLP driver pulls a real SDK, behind the `[export-otlp]` extra.)
+
+The shape it writes
+===================
+
+ONE line per event — the event's own `to_record()` JSON (schema-tagged, byte-clean
+`detail`), the SAME line shape the verdict journal itself writes. That is deliberate:
+the export target is just a SECOND copy of the journal lines at a path a shipper
+already watches, so a downstream parser that already understands a DOS verdict record
+needs no new schema. The append is `O_APPEND` + line-buffered so concurrent appenders
+(a `--follow` drain + a fresh run) never interleave a single line.
+
+Disciplines (inherited from the seam — the `notify_webhook` posture, verbatim)
+==============================================================================
+
+  * **Fail-soft.** `export` returns an `ExportResult`, never raises — no path, an
+    unwritable directory, a full disk, or a non-serializable field all degrade to
+    `exported=0` with a one-line reason. (The seam's `export_safely` is the outer net;
+    this is the inner one, so even a direct `FileExporter().export(...)` is crash-free.)
+  * **Advisory only.** It reads a batch → appends lines. It mutates no DOS state, takes
+    no lease, stops no run, adjudicates nothing. It does NOT rotate or cap the file —
+    that is the log shipper's job (and docs/262 Phase 4's `[retention]` for the journal
+    itself); a file exporter writes, the shipper consumes + truncates.
+
+Routing (the `notify_webhook.resolve_url` ladder, generalized to a path)
+========================================================================
+
+  * **path**: explicit arg › `$DOS_EXPORT_FILE` › the workspace `.env`
+    (`<root>/.env`'s `DOS_EXPORT_FILE`). No path anywhere → a non-exported result. A
+    relative path resolves against the workspace `root` (so `--path verdicts.jsonl`
+    lands under the workspace, not the cwd of whatever drove the drain).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from dos.exporter import ExportResult, _max_seq_cursor
+
+
+def _read_env_file(root: Path) -> dict[str, str]:
+    """Best-effort parse of `<root>/.env` → {KEY: value}. Never raises.
+
+    The `notify_webhook._read_env_file` twin (same parser, different key)."""
+    out: dict[str, str] = {}
+    try:
+        text = (root / ".env").read_text(encoding="utf-8")
+    except OSError:
+        return out
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, _, v = line.partition("=")
+        out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def resolve_path(explicit: str | None, *, root: Path | None) -> str:
+    """Export path: explicit arg › `$DOS_EXPORT_FILE` › `<root>/.env`. "" if none.
+
+    A relative result is resolved against `root` so the export lands under the workspace
+    regardless of the drain's cwd (the `SubstrateConfig.root` anchor; the package never
+    assumes it lives in the repo it serves)."""
+    raw = explicit or os.environ.get("DOS_EXPORT_FILE") or ""
+    if not raw and root is not None:
+        raw = _read_env_file(root).get("DOS_EXPORT_FILE", "")
+    if not raw:
+        return ""
+    p = Path(raw)
+    if not p.is_absolute() and root is not None:
+        p = Path(root) / p
+    return str(p)
+
+
+class FileExporter:
+    """Drain a batch of `VerdictEvent`s by appending each as one JSONL line to a path.
+
+    Parameters
+    ----------
+    path:
+        The export file; defaults to `$DOS_EXPORT_FILE` / the workspace `.env`
+        (`resolve_path`). A relative path resolves against `root`.
+    root:
+        Workspace root for `.env` + relative-path resolution (the `SubstrateConfig.root`).
+    dry_run:
+        Resolve + count + report what WOULD be written, write NOTHING.
+
+    The constructor accepts-and-ignores the export CLI's other superset kwargs
+    (`host`/`port`/`endpoint`) only by NOT declaring them — `exporter._accepted_kwargs`
+    filters the bag to the params below, so a caller can hand the same kwargs to any
+    transport without branching per driver.
+    """
+
+    name = "file"
+
+    def __init__(self, *, path: str = "",
+                 root: "os.PathLike[str] | str | None" = None,
+                 dry_run: bool = False):
+        self._path_arg = path
+        self._root = Path(root) if root is not None else None
+        self._dry_run = bool(dry_run)
+
+    def export(self, events) -> ExportResult:
+        """Append each event as a JSONL line. Returns an `ExportResult`; NEVER raises."""
+        path = resolve_path(self._path_arg, root=self._root)
+        cursor = _max_seq_cursor(events)
+        n = len(events)
+        if not path:
+            return ExportResult(
+                exported=0,
+                detail="no export path (pass --path, set $DOS_EXPORT_FILE, "
+                       "or add DOS_EXPORT_FILE to the workspace .env)",
+                cursor=cursor,
+            )
+
+        if self._dry_run:
+            return ExportResult(
+                exported=0,
+                detail=f"[dry-run] would append {n} event(s) to {path}",
+                cursor=cursor,
+            )
+
+        if n == 0:
+            # Nothing to ship — a perfectly normal drain when no new events landed.
+            return ExportResult(exported=0, detail=f"no new events for {path}", cursor=cursor)
+
+        # Build all the lines first; a single non-serializable field fails the whole
+        # batch cleanly (fail-soft) rather than writing a partial file then raising.
+        try:
+            lines = [
+                json.dumps(e.to_record(), ensure_ascii=False, sort_keys=True)
+                for e in events
+            ]
+        except Exception as e:  # noqa: BLE001 - a bad field must not crash the drain
+            return ExportResult(
+                exported=0, detail=f"error: event not serializable: {e}", cursor=cursor)
+
+        try:
+            p = Path(path)
+            p.parent.mkdir(parents=True, exist_ok=True)
+            # O_APPEND keeps concurrent appends from interleaving a single line (the
+            # verdict_journal.record discipline); we flush so a tailing shipper sees the
+            # lines promptly. No fsync here — the journal is the durable WAL; this is a
+            # best-effort outward copy, and an fsync per drain would throttle a follow loop.
+            with open(p, "a", encoding="utf-8") as fh:
+                fh.write("\n".join(lines) + "\n")
+                fh.flush()
+        except Exception as e:  # noqa: BLE001 - advisory; report, don't crash the producer
+            return ExportResult(exported=0, detail=f"error: {e}", cursor=cursor)
+
+        return ExportResult(
+            exported=n, detail=f"appended {n} event(s) to {path}", cursor=cursor)

dos/drivers/export_otlp.py

@@ -0,0 +1,275 @@
+"""dos.drivers.export_otlp — the OpenTelemetry occupant of `dos.exporter` (docs/266).
+
+The third connector behind the verdict exporter, and the native TRACES/LOGS path. Where
+`export_file` writes JSONL for a shipper to parse and `export_statsd` emits counters,
+THIS driver maps each `VerdictEvent` to an OTLP **log record** — `run_id` as a correlated
+attribute, the byte-clean `detail` counts as attributes — and ships it to an
+OpenTelemetry collector over OTLP/HTTP. So a shop already running an OTel collector
+(Honeycomb, Grafana Tempo/Loki, Datadog's OTLP intake, Jaeger) ingests the verdict
+stream natively, correlated by `run_id`, without a log-tailing or StatsD hop. It
+registers through the `dos.exporters` entry-point group, so `resolve_exporter("otlp")`
+finds it by name and no kernel module imports it.
+
+Why this one needs an extra (`[export-otlp]`)
+=============================================
+
+Unlike `file` + `statsd` (stdlib-only, in the core), OTLP needs a real SDK — the
+`opentelemetry-sdk` + the OTLP/HTTP log exporter. Those live behind the `[export-otlp]`
+extra (the `[mcp]` / `[notify-slack]` precedent), so `pip install dos-kernel` stays
+near-stdlib. The SDK is imported **lazily, inside the transport's `emit`** — never at
+module load — so:
+
+  * entry-point discovery of this driver NEVER fails when the extra is absent (the
+    `notify_slack` lazy-import discipline — importing the driver must be free);
+  * an `export` with the extra absent returns a non-exported `ExportResult` carrying the
+    install hint (`pip install dos-kernel[export-otlp]`), NEVER an ImportError.
+
+The pure part is import-free
+============================
+
+`build_records(events)` turns the batch into a list of NEUTRAL record dicts (severity +
+body + attributes) with NO OpenTelemetry import — so the mapping is golden-shape testable
+without the SDK, and the OTLP-specific construction (LoggerProvider, LogRecord, the HTTP
+exporter) is confined to `_OtlpTransport.emit`, which a test replaces with a fake.
+
+Disciplines (inherited from the seam — the `export_file`/`export_statsd` posture)
+=================================================================================
+
+  * **Fail-soft.** `export` returns an `ExportResult`, never raises — an absent extra, a
+    down collector, a bad endpoint, an SDK error all degrade to `exported=0` with a
+    one-line reason. (The seam's `export_safely` is the outer net; this is the inner one.)
+  * **Advisory only.** It reads a batch → emits records. It mutates no DOS state, takes no
+    lease, stops no run, adjudicates nothing.
+
+Routing
+=======
+
+  * **endpoint**: explicit arg › `$DOS_OTLP_ENDPOINT` › `$OTEL_EXPORTER_OTLP_ENDPOINT`
+    (the OTel standard env) › `<root>/.env` › `http://localhost:4318` (the OTLP/HTTP
+    default). The `/v1/logs` path is appended by the SDK exporter if not present.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dos.exporter import ExportResult, _max_seq_cursor
+
+_DEFAULT_ENDPOINT = "http://localhost:4318"
+_INSTRUMENTATION_SCOPE = "dos.verdict"
+
+# Map the kernel's verdict severity onto the OTLP severity scale. Most verdict tokens are
+# neutral status (ADVANCING/SHIPPED → INFO); the "something is wrong" tokens map to WARN,
+# and the hardest (a run hung / poison) to ERROR. A token not listed is INFO — a verdict
+# is a status record, not inherently an error. (Used by build_records as a NUMBER so the
+# pure part needs no OTel SeverityNumber import; the transport maps it to the enum.)
+_SEVERITY_WARN = {"SPINNING", "DIMINISHING", "COSTLY", "OPEN", "WARN", "DEFER",
+                  "RECENTLY_ATTEMPTED", "QUIET_INCOMPLETE", "HELD", "DIVERGED"}
+_SEVERITY_ERROR = {"STALLED", "WASTEFUL", "BLOCK", "REJECT_POISON", "UNRESUMABLE",
+                   "NOT_SHIPPED"}
+# OTLP SeverityNumber values (stable ints from the spec): INFO=9, WARN=13, ERROR=17.
+_SEV_INFO, _SEV_WARN, _SEV_ERROR = 9, 13, 17
+
+
+def _read_env_file(root: Path) -> dict[str, str]:
+    """Best-effort parse of `<root>/.env` → {KEY: value}. Never raises."""
+    out: dict[str, str] = {}
+    try:
+        text = (root / ".env").read_text(encoding="utf-8")
+    except OSError:
+        return out
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, _, v = line.partition("=")
+        out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def resolve_endpoint(explicit: str | None, *, root: Path | None) -> str:
+    """OTLP endpoint: explicit › `$DOS_OTLP_ENDPOINT` › `$OTEL_EXPORTER_OTLP_ENDPOINT`
+    › `<root>/.env` › http://localhost:4318."""
+    if explicit:
+        return explicit
+    for env_key in ("DOS_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT"):
+        v = os.environ.get(env_key)
+        if v:
+            return v
+    if root is not None:
+        v = _read_env_file(root).get("DOS_OTLP_ENDPOINT")
+        if v:
+            return v
+    return _DEFAULT_ENDPOINT
+
+
+def _severity_number(verdict: str) -> int:
+    """The OTLP severity NUMBER for a verdict token (INFO/WARN/ERROR). Import-free."""
+    v = (verdict or "").upper()
+    if v in _SEVERITY_ERROR:
+        return _SEV_ERROR
+    if v in _SEVERITY_WARN:
+        return _SEV_WARN
+    return _SEV_INFO
+
+
+def build_records(events) -> list[dict]:
+    """A batch of `VerdictEvent`s → neutral OTLP-shaped record dicts (pure; no OTel import).
+
+    Each record carries `body` (a human line `"<syscall> <verdict>"`), `severity_number`
+    (mapped from the verdict token), and `attributes` — the structured, queryable fields a
+    trace/log backend filters on: `dos.syscall`, `dos.verdict`, `dos.run_id` (the
+    correlation key), `dos.lane`/`dos.subject` when present, and each byte-clean
+    `detail.<k>` count flattened with a `dos.detail.` prefix (never the agent's narration —
+    the docs/138 invariant the journal already enforces, carried onto the wire). The
+    transport turns each dict into an OTLP LogRecord; this stays import-free + golden
+    testable, the spine's analogue of `export_statsd.build_lines`.
+    """
+    out: list[dict] = []
+    for e in events:
+        syscall = getattr(e, "syscall", "") or ""
+        verdict = getattr(e, "verdict", "") or ""
+        attrs: dict[str, object] = {
+            "dos.syscall": syscall,
+            "dos.verdict": verdict,
+        }
+        run_id = getattr(e, "run_id", "") or ""
+        if run_id:
+            attrs["dos.run_id"] = run_id
+        lane = getattr(e, "lane", "") or ""
+        if lane:
+            attrs["dos.lane"] = lane
+        subject = getattr(e, "subject", "") or ""
+        if subject:
+            attrs["dos.subject"] = subject
+        source = getattr(e, "source", "") or ""
+        if source:
+            attrs["dos.source"] = source
+        detail = getattr(e, "detail", None) or {}
+        if isinstance(detail, dict):
+            for k, v in detail.items():
+                # OTLP attribute values must be a scalar (or a homogeneous list); coerce
+                # anything else to its string form so a nested/odd value still rides along.
+                attrs[f"dos.detail.{k}"] = v if isinstance(v, (str, int, float, bool)) else str(v)
+        out.append({
+            "body": f"{syscall} {verdict}".strip(),
+            "severity_number": _severity_number(verdict),
+            "attributes": attrs,
+            "ts": getattr(e, "ts", "") or "",
+        })
+    return out
+
+
+class _OtlpTransport:
+    """The lazy OTLP/HTTP log emitter. The ONLY place the OpenTelemetry SDK is imported.
+
+    `emit(records, endpoint)` returns the count emitted; raises `ImportError` when the
+    `[export-otlp]` extra is absent (the driver converts that to an install hint) and any
+    other exception on a transport failure (the driver converts that to a soft error).
+    Kept behind a method so tests inject a fake with the same `emit(records, endpoint)`
+    shape instead of standing up a real collector (the `export_statsd._UdpTransport` /
+    `notify_webhook._UrllibTransport` posture).
+    """
+
+    def emit(self, records: list[dict], endpoint: str) -> int:
+        # Lazy import — absent extra raises ImportError HERE (caught by the driver), never
+        # at module load, so discovering this driver is always free.
+        from opentelemetry._logs import SeverityNumber
+        from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+        from opentelemetry.sdk._logs import LoggerProvider, LogRecord
+        from opentelemetry.sdk._logs.export import SimpleLogRecordProcessor
+        from opentelemetry.sdk.resources import Resource
+
+        resource = Resource.create({"service.name": _INSTRUMENTATION_SCOPE})
+        provider = LoggerProvider(resource=resource)
+        exporter = OTLPLogExporter(endpoint=endpoint)
+        processor = SimpleLogRecordProcessor(exporter)
+        provider.add_log_record_processor(processor)
+        logger = provider.get_logger(_INSTRUMENTATION_SCOPE)
+
+        sent = 0
+        for rec in records:
+            logger.emit(LogRecord(
+                body=rec.get("body", ""),
+                severity_number=SeverityNumber(int(rec.get("severity_number", _SEV_INFO))),
+                attributes=dict(rec.get("attributes", {})),
+            ))
+            sent += 1
+        # Flush so the records leave before the provider is torn down (a short-lived drain,
+        # unlike a long-running app's batching processor).
+        try:
+            provider.force_flush()
+            provider.shutdown()
+        except Exception:  # pragma: no cover - shutdown is best-effort
+            pass
+        return sent
+
+
+class OtlpExporter:
+    """Drain a batch of `VerdictEvent`s as OTLP log records to an OpenTelemetry collector.
+
+    Parameters
+    ----------
+    endpoint:
+        OTLP/HTTP endpoint; defaults to `$DOS_OTLP_ENDPOINT` /
+        `$OTEL_EXPORTER_OTLP_ENDPOINT` / `.env` / http://localhost:4318.
+    root:
+        Workspace root for `.env` resolution (the `SubstrateConfig.root`).
+    dry_run:
+        Build the records + report, emit NOTHING (and never imports the SDK).
+    transport:
+        Inject a fake with an `emit(records, endpoint) -> int` method in tests; None uses
+        the lazy OTLP transport (which needs the `[export-otlp]` extra).
+
+    The constructor accepts-and-ignores the export CLI's `path`/`host`/`port` superset
+    kwargs by NOT declaring them — `exporter._accepted_kwargs` filters the bag to the
+    params below, so a caller hands the same kwargs to any transport without branching.
+    """
+
+    name = "otlp"
+
+    _INSTALL_HINT = ("OTLP exporter needs the [export-otlp] extra — "
+                     "`pip install dos-kernel[export-otlp]`")
+
+    def __init__(self, *, endpoint: str = "",
+                 root: "os.PathLike[str] | str | None" = None,
+                 dry_run: bool = False, transport=None):
+        self._endpoint_arg = endpoint
+        self._root = Path(root) if root is not None else None
+        self._dry_run = bool(dry_run)
+        self._transport = transport
+
+    def export(self, events) -> ExportResult:
+        """Emit one OTLP log record per event. Returns an `ExportResult`; NEVER raises."""
+        cursor = _max_seq_cursor(events)
+        n = len(events)
+        endpoint = resolve_endpoint(self._endpoint_arg, root=self._root)
+
+        if n == 0:
+            return ExportResult(
+                exported=0, detail=f"no new events for {endpoint}", cursor=cursor)
+
+        records = build_records(events)
+
+        if self._dry_run:
+            return ExportResult(
+                exported=0,
+                detail=f"[dry-run] would emit {n} OTLP log record(s) to {endpoint}",
+                cursor=cursor,
+            )
+
+        transport = self._transport if self._transport is not None else _OtlpTransport()
+        try:
+            sent = transport.emit(records, endpoint)
+        except ImportError:
+            # The extra is absent — degrade to the install hint, never an ImportError.
+            return ExportResult(exported=0, detail=self._INSTALL_HINT, cursor=cursor)
+        except Exception as e:  # noqa: BLE001 - advisory; report, don't crash the producer
+            return ExportResult(exported=0, detail=f"error: {e}", cursor=cursor)
+
+        return ExportResult(
+            exported=int(sent),
+            detail=f"emitted {sent} OTLP log record(s) to {endpoint}",
+            cursor=cursor,
+        )