feat: add signal quality and onboarding surfaces

Author: a-a-k

README.md

@@ -87,6 +87,8 @@ go run ./cmd/bering discover \
 
 Expected result: a deterministic `io.mb3r.bering.model@1.1.0` artifact.
 
+`discover` also writes `out/bering-model.signal-quality.json` next to the model.
+
 ### 2) Validate an artifact
 
 ```bash
@@ -109,6 +111,8 @@ go run ./cmd/bering discover \
 
 Expected result: a model artifact plus an `io.mb3r.bering.snapshot@1.1.0` envelope.
 
+The snapshot gets its own `out/bering-snapshot.signal-quality.json` sidecar.
+
 ### 4) Run runtime mode
 
 ```bash
@@ -126,6 +130,8 @@ Useful endpoints:
 - `GET /healthz`
 - `GET /readyz`
 - `GET /metrics`
+- `GET /reconciliation/report`
+- `GET /reconciliation/summary`
 
 ### 5) Use the result with Sheaft
 
@@ -160,6 +166,10 @@ This is the stable topology artifact intended for file-based consumers and tools
 
 This wraps the model with runtime window metadata, ingest counts, coverage, provenance, topology diffs, and discovery-side copies of the same typed placement, resilience, and observed edge metadata.
 
+### Signal quality report
+
+Every batch model, batch snapshot, and runtime snapshot gets a separate `*.signal-quality.json` sidecar. The sidecar reports source mix, provenance, field coverage for typed enrichment fields, and warnings for low-coverage dimensions without changing the public model or snapshot schemas.
+
 ### Runtime reconciliation views
 
 Runtime mode also keeps a conservative reconciliation layer for sparse traffic and telemetry gaps:
@@ -168,6 +178,7 @@ Runtime mode also keeps a conservative reconciliation layer for sparse traffic a
 - `stable_core`: the high-confidence retained view
 - `guardrail_union`: the conservative default downstream artifact
 - a machine-readable reconciliation report for operators
+- an operator-facing reconciliation summary in Markdown
 
 These runtime views do not change the public `io.mb3r.bering.model@1.1.0` or `io.mb3r.bering.snapshot@1.1.0` contracts.
 
@@ -203,6 +214,8 @@ Release outputs include:
 - Batch outputs: [examples/outputs/bering-model.normalized.sample.json](examples/outputs/bering-model.normalized.sample.json), [examples/outputs/bering-snapshot.normalized.sample.json](examples/outputs/bering-snapshot.normalized.sample.json), [examples/outputs/bering-model.topology-api.sample.json](examples/outputs/bering-model.topology-api.sample.json), [examples/outputs/bering-snapshot.topology-api.sample.json](examples/outputs/bering-snapshot.topology-api.sample.json)
 - Runtime config: [configs/serve.sample.yaml](configs/serve.sample.yaml)
 - Discovery overlay: [configs/discovery.overlay.sample.yaml](configs/discovery.overlay.sample.yaml)
+- Enrichment onboarding: [examples/enrichment](examples/enrichment/README.md)
+- Non-trace adapter: [examples/adapters/service-catalog](examples/adapters/service-catalog/README.md)
 - Collector sidecar: [examples/collector/otelcol.sidecar.yaml](examples/collector/otelcol.sidecar.yaml)
 - Prometheus scrape config: [examples/prometheus/bering.prometheus.yml](examples/prometheus/bering.prometheus.yml)
 - Grafana dashboard: [examples/grafana/bering-runtime-dashboard.json](examples/grafana/bering-runtime-dashboard.json)
@@ -216,6 +229,7 @@ Release outputs include:
 - [docs/schema-publishing.md](docs/schema-publishing.md)
 - [docs/trace-input-format.md](docs/trace-input-format.md)
 - [docs/topology-input-format.md](docs/topology-input-format.md)
+- [docs/enrichment-onboarding.md](docs/enrichment-onboarding.md)
 - [docs/mvp-scope-and-limits.md](docs/mvp-scope-and-limits.md)
 - [Delivery tracker](https://github.com/MB3R-Lab/Bering/issues/19)
 - [docs/architecture.md](docs/architecture.md)

configs/serve.sample.yaml

@@ -11,6 +11,7 @@ runtime:
     enabled: true
     state_path: out/reconciliation-state.json
     report_path: out/reconciliation-report.json
+    summary_path: out/reconciliation-summary.md
     raw_window_path: out/latest-raw-window.json
     stable_core_path: out/latest-stable-core.json
     decay_half_life: 10m
@@ -30,6 +31,7 @@ runtime:
 sink:
   directory: out/snapshots
   latest_path: out/latest-snapshot.json
+  signal_quality_path: out/latest-signal-quality.json
 logging:
   structured: true
 overlays:

docs/architecture.md

@@ -11,6 +11,7 @@ Bering now has two user-facing flows built on one normalized discovery core.
 3. The discovery engine or adapter-specific builder produces services, edges, endpoints, confidence, and overlay-driven metadata.
 4. Bering writes the stable `io.mb3r.bering.model` artifact.
 5. Optional `--snapshot-out` also writes a `io.mb3r.bering.snapshot` envelope.
+6. Batch and runtime artifacts get adjacent signal-quality sidecars that report source mix, provenance, and typed-field coverage without changing the public schemas.
 
 ### Runtime flow
 
@@ -27,7 +28,7 @@ The runtime additions are intentionally interface-driven so future connectors ca
 
 - source adapters: normalize external data into internal spans or overlays
 - overlay loaders: decode reusable discovery-side metadata files
-- snapshot sinks: write snapshot envelopes to one or more destinations
+- snapshot sinks: write snapshot envelopes and signal-quality sidecars to one or more destinations
 - clocks: make windowing deterministic in tests
 - storage boundary: one active in-memory tumbling window with an explicit cap
 

docs/enrichment-onboarding.md

@@ -0,0 +1,49 @@
+# Enrichment Onboarding
+
+Bering treats traces, overlays, and `topology_api` inputs as different discovery evidence surfaces.
+
+## Workflow
+
+1. Start with trace-only discovery.
+2. Read the generated `*.signal-quality.json` sidecar.
+3. Add an overlay for curated metadata that traces cannot infer.
+4. Move to `topology_api` when a non-trace system is authoritative for topology, placement, resilience, or endpoint metadata.
+
+## Trace-only baseline
+
+```bash
+go run ./cmd/bering discover \
+  --input examples/traces/normalized.sample.json \
+  --out out/onboarding/trace-only/bering-model.json \
+  --snapshot-out out/onboarding/trace-only/bering-snapshot.json \
+  --discovered-at 2026-03-03T00:00:00Z
+```
+
+The generated signal quality report calls out missing coverage for fields such as `services.placements`, `edges.request_timeout_ms`, `edges.retry_policy`, and `endpoints.custom_success_predicate`.
+
+## Overlay upgrade
+
+```bash
+go run ./cmd/bering discover \
+  --input examples/traces/normalized.sample.json \
+  --overlay examples/enrichment/checkout.overlay.yaml \
+  --out out/onboarding/overlay/bering-model.json \
+  --snapshot-out out/onboarding/overlay/bering-snapshot.json \
+  --discovered-at 2026-03-03T00:00:00Z
+```
+
+Use overlays when the trace-derived topology is acceptable but operational metadata comes from configuration, ownership catalogs, SLO catalogs, or curated policy files.
+
+## topology_api upgrade
+
+```bash
+go run ./cmd/bering discover \
+  --input examples/enrichment/checkout.topology-api.yaml \
+  --out out/onboarding/topology-api/bering-model.json \
+  --snapshot-out out/onboarding/topology-api/bering-snapshot.json \
+  --discovered-at 2026-03-03T00:00:00Z
+```
+
+Use `topology_api` when Bering should publish an explicit topology from a non-trace adapter rather than infer the topology from spans.
+
+Related examples live in [examples/enrichment](../examples/enrichment/README.md).

docs/runtime-config.md

@@ -70,6 +70,7 @@ Suggested fields:
 - `enabled`: toggle the reconciliation module on or off
 - `state_path`: JSON file used to persist reconciliation state between windows and restarts
 - `report_path`: machine-readable report file for the latest reconciliation result
+- `summary_path`: operator-facing Markdown summary for the latest reconciliation result
 - `decay_half_life`: controls how quickly older evidence loses weight
 - `minimum_opportunity_windows`: minimum opportunity evidence before misses can count
 - `telemetry_health_freeze_threshold`: freeze or heavily damp retirement below this score
@@ -95,6 +96,14 @@ Optional stable path that is rewritten on every successful snapshot.
 
 Example: `out/latest-snapshot.json`
 
+### `sink.signal_quality_path`
+
+Stable path for the latest signal quality and field coverage report.
+
+Example: `out/latest-signal-quality.json`
+
+Each timestamped snapshot also gets an adjacent `*.signal-quality.json` sidecar.
+
 ### `logging.structured`
 
 Emit JSON logs instead of text logs.
@@ -126,7 +135,9 @@ overlays:
 - `--reconciliation-enabled`
 - `--reconciliation-state-path`
 - `--reconciliation-report-path`
+- `--reconciliation-summary-path`
 - `--sink-dir`
 - `--latest-path`
+- `--signal-quality-path`
 - `--log-format text|json`
 - `--overlay` (repeatable)

docs/topology-input-format.md

@@ -4,6 +4,8 @@ Bering supports an explicit non-trace batch source: `topology_api`.
 
 Use this when topology, placement, or resilience metadata already exists in a service registry, mesh export, inventory API, or curated file and you want Bering to publish the same stable model and snapshot artifacts without trace inference.
 
+A reference non-trace adapter lives at [examples/adapters/service-catalog](../examples/adapters/service-catalog/README.md). It converts a small service catalog JSON document into `topology_api` JSON before calling `bering discover`.
+
 ## Contract line
 
 - `bering discover` now emits `io.mb3r.bering.model@1.1.0` and `io.mb3r.bering.snapshot@1.1.0` by default.

examples/adapters/service-catalog/README.md

@@ -0,0 +1,23 @@
+# Service Catalog Adapter Example
+
+This is a reference non-trace adapter. It reads a small service catalog JSON file and emits Bering `topology_api` JSON.
+
+Generate topology input:
+
+```bash
+go run ./examples/adapters/service-catalog \
+  --input examples/adapters/service-catalog/catalog.sample.json \
+  --out out/adapters/service-catalog/topology-api.json
+```
+
+Run Bering discovery on the generated topology:
+
+```bash
+go run ./cmd/bering discover \
+  --input out/adapters/service-catalog/topology-api.json \
+  --out out/adapters/service-catalog/bering-model.json \
+  --snapshot-out out/adapters/service-catalog/bering-snapshot.json \
+  --discovered-at 2026-03-03T00:00:00Z
+```
+
+The adapter is intentionally plain Go and has no service-catalog dependency. Real adapters should map their source-specific concepts into the same `topology_api` fields shown here: services, placements, shared resources, dependencies, resilience policy, policy scope, and endpoints.

examples/adapters/service-catalog/catalog.sample.json

@@ -0,0 +1,83 @@
+{
+  "source_ref": "service-catalog://checkout-sample",
+  "services": [
+    {
+      "id": "frontend",
+      "replicas": 2,
+      "team": "web",
+      "tier": "edge"
+    },
+    {
+      "id": "checkout",
+      "replicas": 3,
+      "team": "commerce",
+      "tier": "backend",
+      "failure_eligible": true,
+      "placements": [
+        {
+          "replicas": 2,
+          "labels": {
+            "region": "us-east-1",
+            "az": "us-east-1a"
+          }
+        },
+        {
+          "replicas": 1,
+          "labels": {
+            "region": "us-east-1",
+            "az": "us-east-1b"
+          }
+        }
+      ],
+      "shared_resources": [
+        "kafka-orders",
+        "payments-db"
+      ]
+    },
+    {
+      "id": "payment",
+      "replicas": 2,
+      "team": "payments",
+      "tier": "backend",
+      "failure_eligible": true
+    }
+  ],
+  "dependencies": [
+    {
+      "from": "frontend",
+      "to": "checkout",
+      "mode": "sync",
+      "blocking": true,
+      "weight": 0.85,
+      "request_timeout_ms": 2000,
+      "retry_max_attempts": 3,
+      "circuit_breaker_enabled": true,
+      "source_endpoint_id": "frontend:GET /checkout",
+      "method": "GET",
+      "route": "/checkout"
+    },
+    {
+      "from": "checkout",
+      "to": "payment",
+      "mode": "async",
+      "blocking": false,
+      "weight": 0.35
+    }
+  ],
+  "endpoints": [
+    {
+      "service": "frontend",
+      "method": "GET",
+      "path": "/checkout",
+      "predicate_ref": "catalog.frontend.checkout.success",
+      "weight": 0.7
+    },
+    {
+      "service": "checkout",
+      "method": "POST",
+      "path": "/process",
+      "predicate_ref": "catalog.checkout.process.success",
+      "weight": 0.6
+    }
+  ]
+}