/using-lib-systemplane

name: ring:using-lib-systemplane
description: "Using lib-systemplane, the hot-reload runtime-config plane (Postgres LISTEN/NOTIFY or MongoDB change streams), in two modes. Sweep Mode detects DIY config reload (SIGHUP, fsnotify, viper, pgx LISTEN), manual tenant-scoping, hand-built admin CRUD, and v4 residue. Reference Mode catalogs client lifecycle and migration-only provisioning. Go-only. Gated migration goes to ring:migrating-to-lib-systemplane. Skip for non-Go."

ring:using-lib-systemplane

When to use

Sweep mode:

• "Sweep the codebase for lib-systemplane opportunities"
• "Find where we hot-reload config DIY (SIGHUP, fsnotify, viper.WatchConfig)"
• "Audit this service for lib-systemplane adoption"
• "Find raw pgx LISTEN / Mongo change-stream watchers wired against config tables"
• "Detect v4 systemplane residue (Supervisor, BundleFactory, SYSTEMPLANE_* env vars)"

Reference mode:

• "What does lib-systemplane provide?"
• "How do I construct the client for Postgres / MongoDB?"
• "Show me Register vs RegisterTenantScoped"
• "Which read accessor should I use for a duration / int / bool?"
• "How do OnChange and OnTenantChange differ?"
• "How do I mount the admin HTTP surface safely?"
• "What does the test harness look like?"

Skip when

• Working on non-Go services
• Working on frontend code
• Target codebase has zero hot-reloadable runtime knobs (everything is static env-var-at-startup config — DSNs, TLS material, listen addresses, secrets stay outside the plane)
• Task is documentation-only or non-code

Related

**Migration partner:** `ring:migrating-to-lib-systemplane` — end-to-end 11-gate migration cycle. This skill is the **adoption/reference** counterpart; the migration skill is the **transformation pipeline**. **Similar:** [[ring:using-lib-commons]], [[ring:using-lib-observability]], [[ring:using-runtime]], [[ring:using-assert]]

---

Mode Selection

| Request Shape | Mode | |---|---| | "Sweep / audit / find DIY runtime config / migrate to lib-systemplane" | **Sweep** | | "What does lib-systemplane provide for X?" | **Reference** | | "How do I initialize / register / subscribe?" | **Reference** | | "Replace our fsnotify + SIGHUP plumbing with lib-systemplane" | **Sweep** | | "Wire admin routes onto our Fiber app" | **Reference** |

---

Module Facts (lock-checked)

• **Module path:** `github.com/LerianStudio/lib-systemplane`
• **Go version:** 1.26.3+
• **Tenant context:** `github.com/LerianStudio/lib-commons/v5 v5.0.2` (via `tenant-manager/core`)
• **Observability:** `github.com/LerianStudio/lib-observability v1.1.0` (`log.Logger`, `tracing.Telemetry`, `runtime.RecoverAndLog`)
• **Dual backend:** Postgres 13+ (LISTEN/NOTIFY) **or** MongoDB 4.4+ (change streams; polling fallback for standalone deployments)
• **Provisioning:** migration-only via `systemplane.SchemaSQL()` + `systemplane.DefaultSeedSQL()` public artifacts. Runtime DDL hook (`runSchema`) was removed in v1.6.0. Consumers vendor the artifacts into their own SQL migration pipeline via the `make systemplane-ddl` generator pattern — see `ring:migrating-to-lib-systemplane` Gate 3.5 and `multi-tenant.md` §27 "Cold-tenant resolution"
• **License:** Elastic 2.0
• **Scope:** runtime-mutable knobs only — never bootstrap-only material (DSNs, TLS, listen addresses, secrets)

---

SWEEP MODE

Orchestrate a 4-phase sweep. Each phase has a hard gate — do not proceed until the current phase produces its artifact.

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

Phase 1: Version Reconnaissance

1. Read `go.mod` — search for `github.com/LerianStudio/lib-systemplane` and any v4-era `github.com/LerianStudio/lib-commons/v[34]/commons/systemplane` imports 2. WebFetch `https://api.github.com/repos/LerianStudio/lib-systemplane/releases/latest` — extract `tag_name` 3. Classify drift: `not-adopted` / `up-to-date` / `minor-drift` / `moderate-drift` / `major-upgrade` / `v4-residue` 4. If any `v4/commons/systemplane` or `Supervisor`/`BundleFactory` import survives → flag `v4-residue: true` 5. Emit `/tmp/systemplane-version-report.json`: `{adopted, pinned_version, latest_version, drift_classification, v4_residue, module_path}`

Phase 2: CHANGELOG Delta Analysis

1. WebFetch `https://raw.githubusercontent.com/LerianStudio/lib-systemplane/main/CHANGELOG.md` 2. Extract entries between pinned_version (exclusive) and latest_version (inclusive). If not yet adopted, summarize the whole CHANGELOG. 3. Classify each entry: `new-api` / `breaking-change` / `tenant-feature` / `admin-feature` / `security-fix` / `performance` / `bugfix` 4. Cross-reference `MIGRATION_TENANT_SCOPED.md` for two-phase rolling-deploy implications when adopting tenant overrides 5. Emit `/tmp/systemplane-delta-report.json` with classified entries

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 7.
• If count < 7 → STOP. Do not partial-dispatch. Reconcile against the 7 angles below and try again.
• The 7 angles are the canonical sweep. No substitutions, no omissions.

⛔ MUST NOT trickle-dispatch

All 7 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