Merge pull request #16 from MB3R-Lab/feat/mvp-bootstrap-contract

[MVP][PR2] Discover/validate CLI + deterministic artifact + examples/docs

Author: a-a-k

cmd/bering/main.go

@@ -0,0 +1,12 @@
+package main
+
+import (
+	"os"
+
+	"github.com/MB3R-Lab/Bering/internal/app"
+)
+
+func main() {
+	runner := app.NewRunner(os.Stdout, os.Stderr)
+	os.Exit(runner.Run(os.Args[1:]))
+}

configs/replicas.sample.yaml

@@ -0,0 +1,6 @@
+replicas:
+  frontend: 2
+  checkout: 3
+  payment: 2
+  inventory: 2
+

docs/mvp-scope-and-limits.md

@@ -0,0 +1,31 @@
+# MVP Scope and Limits
+
+## In scope
+
+- Discover model from trace files/directories.
+- Emit Sheaft-compatible `bering-model.json` (v1.0.0 contract).
+- Validate artifact with strict `metadata.schema` match.
+- Deterministic output ordering and canonical JSON serialization.
+
+## Out of scope (MVP)
+
+- Non-trace connectors (runtime service registries, topology APIs).
+- Advanced dependency semantics (timeouts, retries, circuit breakers).
+- Correlated failures and probabilistic calibration from production data.
+- Multi-version schema negotiation.
+
+## Confidence heuristic (MVP)
+
+`metadata.confidence` is deterministic and computed from discovery coverage:
+
+- base score: `0.35`
+- `+0.20` if more than one service discovered
+- `+0.15` if at least one edge discovered
+- `+0.15` if at least one endpoint inferred
+- `+min(0.15, cross_service_parent_child_ratio * 0.15)`
+
+Result is clamped to `[0,1]` and rounded to 2 decimals.
+
+This score is informational in MVP and should not be interpreted as a calibrated
+probability of correctness.
+

docs/trace-input-format.md

@@ -0,0 +1,67 @@
+# Trace Input Format (MVP)
+
+Bering MVP supports two JSON input formats.
+
+## 1) Normalized spans JSON
+
+Top-level shape:
+
+```json
+{
+  "spans": [
+    {
+      "trace_id": "trace-1",
+      "span_id": "span-1",
+      "parent_span_id": "",
+      "service": "frontend",
+      "kind": "server",
+      "name": "GET /checkout",
+      "attributes": {
+        "http.request.method": "GET",
+        "http.route": "/checkout"
+      }
+    }
+  ]
+}
+```
+
+Accepted aliases:
+
+- `traceId` for `trace_id`
+- `spanId` for `span_id`
+- `parentSpanId` for `parent_span_id`
+- `service_name` or `service.name` for `service`
+
+## 2) Raw OTel JSON payload
+
+Expected hierarchy:
+
+- `resourceSpans[]`
+- `resourceSpans[].resource.attributes[]`
+- `resourceSpans[].scopeSpans[]` (or `instrumentationLibrarySpans[]`)
+- `...scopeSpans[].spans[]`
+
+Supported OTel fields:
+
+- `traceId`, `spanId`, `parentSpanId`, `name`, `kind`
+- resource/span attributes in key/value form (`key` + `value.stringValue|intValue|doubleValue|boolValue`)
+
+`service.name` is resolved from resource attributes first, then span attributes.
+
+## Discovery-relevant attributes
+
+- HTTP endpoint inference:
+  - `http.request.method`, `http.method`
+  - `http.route`, `url.path`, `http.target`
+- Async edge heuristic:
+  - `messaging.system`
+  - `messaging.destination`
+  - `messaging.operation`
+  - span kind `producer` or `consumer`
+
+## Input mode
+
+- `--input` can point to:
+  - a single JSON file
+  - a directory (all `*.json` files recursively, sorted by path)
+

examples/outputs/bering-model.normalized.sample.json

@@ -0,0 +1,73 @@
+{
+  "edges": [
+    {
+      "blocking": true,
+      "from": "checkout",
+      "kind": "sync",
+      "to": "inventory"
+    },
+    {
+      "blocking": false,
+      "from": "checkout",
+      "kind": "async",
+      "to": "payment"
+    },
+    {
+      "blocking": true,
+      "from": "frontend",
+      "kind": "sync",
+      "to": "checkout"
+    }
+  ],
+  "endpoints": [
+    {
+      "entry_service": "checkout",
+      "id": "checkout:POST /process",
+      "success_predicate_ref": "checkout:POST /process"
+    },
+    {
+      "entry_service": "frontend",
+      "id": "frontend:GET /checkout",
+      "success_predicate_ref": "frontend:GET /checkout"
+    },
+    {
+      "entry_service": "frontend",
+      "id": "frontend:GET /health",
+      "success_predicate_ref": "frontend:GET /health"
+    }
+  ],
+  "metadata": {
+    "confidence": 0.94,
+    "discovered_at": "2026-03-03T00:00:00Z",
+    "schema": {
+      "digest": "sha256:7dc733936a9d3f94ab92f46a30d4c8d0f5c05d60670c4247786c59a3fe7630f7",
+      "name": "io.mb3r.bering.model",
+      "uri": "https://schemas.mb3r.dev/bering/model/v1.0.0/model.schema.json",
+      "version": "1.0.0"
+    },
+    "source_ref": "bering://discover?input=examples%2Ftraces%2Fnormalized.sample.json",
+    "source_type": "bering"
+  },
+  "services": [
+    {
+      "id": "checkout",
+      "name": "checkout",
+      "replicas": 1
+    },
+    {
+      "id": "frontend",
+      "name": "frontend",
+      "replicas": 1
+    },
+    {
+      "id": "inventory",
+      "name": "inventory",
+      "replicas": 1
+    },
+    {
+      "id": "payment",
+      "name": "payment",
+      "replicas": 1
+    }
+  ]
+}

examples/outputs/bering-model.otel.sample.json

@@ -0,0 +1,73 @@
+{
+  "edges": [
+    {
+      "blocking": true,
+      "from": "checkout",
+      "kind": "sync",
+      "to": "inventory"
+    },
+    {
+      "blocking": false,
+      "from": "checkout",
+      "kind": "async",
+      "to": "payment"
+    },
+    {
+      "blocking": true,
+      "from": "frontend",
+      "kind": "sync",
+      "to": "checkout"
+    }
+  ],
+  "endpoints": [
+    {
+      "entry_service": "checkout",
+      "id": "checkout:POST /process",
+      "success_predicate_ref": "checkout:POST /process"
+    },
+    {
+      "entry_service": "frontend",
+      "id": "frontend:GET /checkout",
+      "success_predicate_ref": "frontend:GET /checkout"
+    },
+    {
+      "entry_service": "frontend",
+      "id": "frontend:GET /health",
+      "success_predicate_ref": "frontend:GET /health"
+    }
+  ],
+  "metadata": {
+    "confidence": 0.94,
+    "discovered_at": "2026-03-03T00:00:00Z",
+    "schema": {
+      "digest": "sha256:7dc733936a9d3f94ab92f46a30d4c8d0f5c05d60670c4247786c59a3fe7630f7",
+      "name": "io.mb3r.bering.model",
+      "uri": "https://schemas.mb3r.dev/bering/model/v1.0.0/model.schema.json",
+      "version": "1.0.0"
+    },
+    "source_ref": "bering://discover?input=examples%2Ftraces%2Fotel.sample.json",
+    "source_type": "bering"
+  },
+  "services": [
+    {
+      "id": "checkout",
+      "name": "checkout",
+      "replicas": 1
+    },
+    {
+      "id": "frontend",
+      "name": "frontend",
+      "replicas": 1
+    },
+    {
+      "id": "inventory",
+      "name": "inventory",
+      "replicas": 1
+    },
+    {
+      "id": "payment",
+      "name": "payment",
+      "replicas": 1
+    }
+  ]
+}

examples/traces/normalized.sample.json

@@ -0,0 +1,59 @@
+{
+  "spans": [
+    {
+      "trace_id": "t-checkout",
+      "span_id": "frontend-1",
+      "service": "frontend",
+      "kind": "server",
+      "name": "GET /checkout",
+      "attributes": {
+        "http.request.method": "GET",
+        "http.route": "/checkout"
+      }
+    },
+    {
+      "trace_id": "t-checkout",
+      "span_id": "checkout-1",
+      "parent_span_id": "frontend-1",
+      "service": "checkout",
+      "kind": "server",
+      "name": "POST /process",
+      "attributes": {
+        "http.request.method": "POST",
+        "http.route": "/process"
+      }
+    },
+    {
+      "trace_id": "t-checkout",
+      "span_id": "payment-1",
+      "parent_span_id": "checkout-1",
+      "service": "payment",
+      "kind": "consumer",
+      "name": "kafka consume payment-events",
+      "attributes": {
+        "messaging.system": "kafka",
+        "messaging.destination": "payment-events"
+      }
+    },
+    {
+      "trace_id": "t-checkout",
+      "span_id": "inventory-1",
+      "parent_span_id": "checkout-1",
+      "service": "inventory",
+      "kind": "client",
+      "name": "reserve inventory"
+    },
+    {
+      "trace_id": "t-health",
+      "span_id": "frontend-2",
+      "service": "frontend",
+      "kind": "server",
+      "name": "GET /health",
+      "attributes": {
+        "http.request.method": "GET",
+        "http.route": "/health"
+      }
+    }
+  ]
+}
+