ring:using-runtime

---
name: ring-using-runtime-b25592e9e615
description: "Using lib-observability/runtime, which turns silent goroutine deaths into log/span/metric signal, in two modes. Sweep Mode detects naked goroutines, unobservable defer recover(), missing InitPanicMetrics, and lib-commons/v5 shim imports. Reference Mode catalogs SafeGo, RecoverWithPolicy, the policy decision tree, and Fiber/gRPC/RabbitMQ integration. Go-only. Skip for non-Go or frontend code."
---

# ring:using-runtime

## Moved from lib-commons

The `runtime` package lived in `lib-commons` through v4 and the v5 shim period.
Its canonical home is now **`github.com/LerianStudio/lib-observability/runtime`** (v1.0.0+).
`lib-commons` v5 keeps a deprecated compatibility shim at
`github.com/LerianStudio/lib-commons/v5/commons/runtime` that re-exports every symbol
from lib-observability — existing imports keep compiling, but the shim is marked
`Deprecated:` in package docs and will be removed in a future lib-commons major. New
code MUST import from `lib-observability/runtime` directly; sweeps SHOULD also flag
imports still pointing at the lib-commons shim as a follow-up migration.

## When to use
Sweep mode:
- "Sweep / audit panic handling"
- "Find naked goroutines"
- "Migrate this service to lib-observability/runtime"
- "Are our defer recover() calls observable?"

Reference mode:
- "Which SafeGo variant do I use for X?"
- "How does the observability trident fire on panic?"
- "Show me the policy decision tree"
- "How do I wire runtime into Fiber / gRPC / RabbitMQ?"

## Skip when
- Working on non-Go services
- Working on frontend code

## Related
**Parent:** ring:using-lib-observability (canonical home of the `runtime` package)
**Similar:** ring:using-lib-commons (lifecycle / App glue still lives there), ring:using-assert


Extends `ring:using-lib-observability` panic-handling coverage into 6 focused sub-angles
with deeper detection patterns, full API reference, policy decision tree, and framework integrations.
Also extends `ring:using-lib-commons` Angle 15 (Panic handling DIY) for codebases still
on the v5 shim path. Use when panic handling is the primary concern or when the parent
sweep surfaced significant findings.

## Mode Selection

| Request Shape | Mode |
|---|---|
| "Sweep / audit panic handling / find naked goroutines" | **Sweep** |
| "Which SafeGo variant do I use?" | **Reference** |
| "Policy decision tree" | **Reference** |
| "Framework integration (Fiber/gRPC/RabbitMQ)" | **Reference** |

---

# SWEEP MODE

4-phase sweep. Each phase has a hard gate.

```
Phase 1: Version Reconnaissance   → runtime-version-report.json
Phase 2: CHANGELOG Delta Analysis → runtime-delta-report.json
Phase 3: Multi-Angle DIY Sweep    → 6 × runtime-sweep-{N}-{angle}.json
Phase 4: Consolidated Report      → runtime-sweep-report.md + runtime-sweep-tasks.json
```

## Phase 1: Version Reconnaissance

1. Read `go.mod` — extract pinned version of `github.com/LerianStudio/lib-observability`
   (canonical) AND any pinned `github.com/LerianStudio/lib-commons/vN` (shim path)
2. WebFetch `https://api.github.com/repos/LerianStudio/lib-observability/releases/latest`
   — extract `tag_name` for the canonical library
3. If the target imports `lib-commons/v5/commons/runtime` (deprecated shim), record
   `shim_import_detected: true` — this is itself a follow-up migration finding
4. Classify drift; emit `/tmp/runtime-version-report.json`

## Phase 2: CHANGELOG Delta Analysis

1. WebFetch `https://raw.githubusercontent.com/LerianStudio/lib-observability/main/CHANGELOG.md`
2. Filter entries affecting the `runtime` package
3. If `shim_import_detected` from Phase 1, also WebFetch
   `https://raw.githubusercontent.com/LerianStudio/lib-commons/main/CHANGELOG.md` and
   filter for `commons/runtime` shim-deprecation entries
4. Emit `/tmp/runtime-delta-report.json`

## Phase 3: Multi-Angle DIY Sweep

### ⛔ STOP-CHECK BEFORE DISPATCH

Before emitting any Task call, count the explorers you intend to launch in this turn.
- Count MUST equal 6.
- If count < 6 → STOP. Do not partial-dispatch. Reconcile against the 6 angles below and try again.
- The 6 angles are the canonical sweep. No substitutions, no omissions.

### ⛔ MUST NOT trickle-dispatch

All 6 explorers leave in the SAME TURN, before reading any explorer output.

Forbidden sequences:
- Dispatch explorer 1 → read result → dispatch explorer 2
- Dispatch a subset → wait → dispatch the rest
- Dispatch follow-up explorers conditioned on partial output
- Loop sequentially over the angle list

If you find yourself about to dispatch an explorer in a turn AFTER any explorer has already returned a result → STOP. You violated parallel dispatch. Report the violation and mark the phase INCOMPLETE rather than completing the trickle.

### Self-verify after dispatch

After the dispatch turn, verify all 6 Task calls were emitted in that single turn. If fewer than 6 went out, the phase did NOT execute correctly. Mark INCOMPLETE and surface the dispatch failure — do NOT silently continue with a partial pool.

### Parallel dispatch — atomic batch

Emit all 6 Task calls in a SINGLE TURN, as one atomic batch.

**If your runtime exposes a `multi_tool_use.parallel` wrapper**, use it to dispatch the complete pool in one wrapped invocation. This is the canonical fan-out mechanism on OpenAI-style tool envelopes and on certain Anthropic SDK consumers — naming it explicitly activates parallel emission on runtimes where trickle-dispatch is the default behavior.

**If your runtime emits parallel tool_use blocks natively** (Claude Code with Claude models), `multi_tool_use.parallel` may not be needed — but naming it is harmless and serves as an enforcement anchor.

The STOP-CHECK, anti-trickle, and self-verify guards above remain binding regardless of which mechanism your runtime uses.

Dispatch all 6 explorer angles in **one parallel batch**. Wait for all before Phase 4.

**Per-explorer dispatch** (`subagent_type: ring:codebase-explorer`):

```
## Target: <absolute path>
## Your Angle: <angle number + name>
## Severity / DIY Patterns / Replacement / Migration Complexity / Version Context
<verbatim from sub-files/sweep-angles.md for this angle>

## Output
Write to: /tmp/runtime-sweep-{N}-{angle-slug}.json
Schema: { angle_number, angle_name, severity, migration_complexity,
  findings: [{file, line, diy_pattern, replacement, evidence_snippet, notes}],
  summary, requires_major_upgrade }
If no findings: write file with empty findings array.
```

Full angle specifications: `sub-files/sweep-angles.md`

The 6 angles cover:
1. Naked goroutine launches (CRITICAL)
2. Unobservable `defer recover()` (CRITICAL)
3. Missing `InitPanicMetrics` at startup (HIGH)
4. Missing `SetProductionMode(true)` in production (HIGH)
5. Framework panic handlers bypassing `HandlePanicValue` (HIGH)
6. Policy mismatch — KeepRunning vs CrashProcess (MEDIUM)

## Phase 4: Consolidated Report

Dispatch synthesizer to read all 6 files and emit:
1. `/tmp/runtime-sweep-report.md`
2. `/tmp/runtime-sweep-tasks.json`

Surface report path + task count; offer handoff to `ring:running-dev-cycle`.

---

# REFERENCE MODE

Full API reference in `sub-files/reference.md`. Load sections relevant to your task.

## Quick Navigation

| # | Section | What you'll find |
|---|---|---|
| 1 | API Surface | SafeGo / RecoverWithPolicy / HandlePanicValue / Init / SetProductionMode |
| 2 | Policy Decision Tree | KeepRunning vs CrashProcess |
| 3 | Pattern Catalog | Consumer loops, fan-out, tickers, Fiber/gRPC/RabbitMQ |
| 4 | Observability Trident | Log + span event + metric on panic |
| 5 | Testing Patterns | Proving recovery fires |
| 6 | Anti-Pattern Catalog | Six failure modes |
| 7 | Bootstrap Order | Where runtime setup fits in init |
| 8–10 | Cross-Cutting, Breaking Changes, Cross-References | v4→v5 delta |

Read `sub-files/reference.md` for full API detail.