Refactor code structure for improved readability and maintainability; optimize performance in key functions.

docs/modules/concelier/operations/connectors/alpine.md

@@ -0,0 +1,53 @@
+# Concelier Alpine SecDB Connector - Operations Runbook
+
+_Last updated: 2025-12-22_
+
+## 1. Overview
+The Alpine connector pulls JSON secdb feeds (main/community) for configured
+releases and maps CVE identifiers to APK version ranges. It preserves native
+APK versions and emits `rangeKind: apk` so downstream consumers keep distro
+semantics intact.
+
+## 2. Configuration knobs (`concelier.yaml`)
+```yaml
+concelier:
+  sources:
+    alpine:
+      baseUri: "https://secdb.alpinelinux.org/"
+      releases:
+        - "v3.18"
+        - "v3.19"
+        - "v3.20"
+      repositories:
+        - "main"
+        - "community"
+      maxDocumentsPerFetch: 20
+      fetchTimeout: "00:00:45"
+      requestDelay: "00:00:00"
+      userAgent: "StellaOps.Concelier.Alpine/0.1 (+https://stella-ops.org)"
+```
+
+### Recommendations
+- Keep `releases` to supported Alpine branches only; avoid stale branches in
+  production unless you maintain a mirror.
+- Use `requestDelay` when running multiple source connectors on shared egress.
+
+## 3. Default job schedule
+
+| Job kind | Cron | Timeout | Lease |
+|----------|------|---------|-------|
+| `source:alpine:fetch` | `*/30 * * * *` | 5 minutes | 4 minutes |
+| `source:alpine:parse` | `7,37 * * * *` | 6 minutes | 4 minutes |
+| `source:alpine:map` | `12,42 * * * *` | 8 minutes | 4 minutes |
+
+The cadence staggers fetch, parse, and map so each stage has a clean window to
+complete. Override via `concelier.jobs.definitions[...]` when coordinating
+multiple sources on the same scheduler.
+
+## 4. Offline and air-gapped deployments
+- Mirror `secdb` JSON files into a local repository and point `baseUri` to the
+  mirror host.
+- The connector allowlists only the `baseUri` host; update it to match the
+  internal mirror host.
+- Keep fixtures and exported bundles deterministic by leaving the order of
+  releases and repositories stable.