Implement first public product release of Bering (v0.1.0)

Add CHANGELOG.md to document the initial release highlights, including batch discovery capabilities, artifact validation, and runtime service features. Update README.md to reflect the new product version and clarify installation instructions. Enhance RELEASING.md and VERSIONING.md to outline the separation of product and schema versioning. Modify CI workflows for schema publishing and release automation, ensuring proper artifact management. Update documentation to support the new release structure and clarify usage with Sheaft.

Author: a-a-k

.github/workflows/publish-schema.yml

@@ -36,11 +36,14 @@ jobs:
             grep -E "^[[:space:]]*${key}[[:space:]]*=" internal/schema/constants.go | sed -E 's/.*"([^"]+)".*/\1/'
           }
 
-          SCHEMA_VERSION="$(extract_const ExpectedSchemaVersion)"
-          SCHEMA_URI="$(extract_const ExpectedSchemaURI)"
-          SCHEMA_DIGEST="$(extract_const ExpectedSchemaDigest)"
-
-          if [[ -z "${SCHEMA_VERSION}" || -z "${SCHEMA_URI}" || -z "${SCHEMA_DIGEST}" ]]; then
+          MODEL_SCHEMA_VERSION="$(extract_const ExpectedSchemaVersion)"
+          MODEL_SCHEMA_URI="$(extract_const ExpectedSchemaURI)"
+          MODEL_SCHEMA_DIGEST="$(extract_const ExpectedSchemaDigest)"
+          SNAPSHOT_SCHEMA_VERSION="$(extract_const ExpectedSnapshotSchemaVersion)"
+          SNAPSHOT_SCHEMA_URI="$(extract_const ExpectedSnapshotSchemaURI)"
+          SNAPSHOT_SCHEMA_DIGEST="$(extract_const ExpectedSnapshotSchemaDigest)"
+
+          if [[ -z "${MODEL_SCHEMA_VERSION}" || -z "${MODEL_SCHEMA_URI}" || -z "${MODEL_SCHEMA_DIGEST}" || -z "${SNAPSHOT_SCHEMA_VERSION}" || -z "${SNAPSHOT_SCHEMA_URI}" || -z "${SNAPSHOT_SCHEMA_DIGEST}" ]]; then
             echo "failed to resolve schema constants from internal/schema/constants.go"
             exit 1
           fi
@@ -51,24 +54,29 @@ jobs:
               exit 1
             fi
             TAG_VERSION="${GITHUB_REF_NAME#schema-v}"
-            if [[ "${TAG_VERSION}" != "${SCHEMA_VERSION}" ]]; then
-              echo "tag version mismatch: tag=${TAG_VERSION} schema=${SCHEMA_VERSION}"
+            if [[ "${TAG_VERSION}" != "${MODEL_SCHEMA_VERSION}" || "${TAG_VERSION}" != "${SNAPSHOT_SCHEMA_VERSION}" ]]; then
+              echo "tag version mismatch: tag=${TAG_VERSION} model=${MODEL_SCHEMA_VERSION} snapshot=${SNAPSHOT_SCHEMA_VERSION}"
               exit 1
             fi
           else
-            TAG_VERSION="${SCHEMA_VERSION}"
+            TAG_VERSION="${MODEL_SCHEMA_VERSION}"
           fi
 
-          echo "schema_version=${SCHEMA_VERSION}" >> "${GITHUB_OUTPUT}"
-          echo "schema_uri=${SCHEMA_URI}" >> "${GITHUB_OUTPUT}"
-          echo "schema_digest=${SCHEMA_DIGEST}" >> "${GITHUB_OUTPUT}"
+          echo "model_schema_version=${MODEL_SCHEMA_VERSION}" >> "${GITHUB_OUTPUT}"
+          echo "model_schema_uri=${MODEL_SCHEMA_URI}" >> "${GITHUB_OUTPUT}"
+          echo "model_schema_digest=${MODEL_SCHEMA_DIGEST}" >> "${GITHUB_OUTPUT}"
+          echo "snapshot_schema_version=${SNAPSHOT_SCHEMA_VERSION}" >> "${GITHUB_OUTPUT}"
+          echo "snapshot_schema_uri=${SNAPSHOT_SCHEMA_URI}" >> "${GITHUB_OUTPUT}"
+          echo "snapshot_schema_digest=${SNAPSHOT_SCHEMA_DIGEST}" >> "${GITHUB_OUTPUT}"
           echo "tag_version=${TAG_VERSION}" >> "${GITHUB_OUTPUT}"
 
       - name: Validate schema JSON and $id binding
         shell: bash
         env:
-          EXPECTED_URI: ${{ steps.contract.outputs.schema_uri }}
-          EXPECTED_DIGEST: ${{ steps.contract.outputs.schema_digest }}
+          EXPECTED_MODEL_URI: ${{ steps.contract.outputs.model_schema_uri }}
+          EXPECTED_MODEL_DIGEST: ${{ steps.contract.outputs.model_schema_digest }}
+          EXPECTED_SNAPSHOT_URI: ${{ steps.contract.outputs.snapshot_schema_uri }}
+          EXPECTED_SNAPSHOT_DIGEST: ${{ steps.contract.outputs.snapshot_schema_digest }}
         run: |
           set -euo pipefail
           python - <<'PY'
@@ -77,45 +85,93 @@ jobs:
           import os
           from pathlib import Path
 
-          schema_path = Path("api/schema/model.schema.json")
-          raw = schema_path.read_bytes()
-          payload = json.loads(raw.decode("utf-8"))
-          expected_uri = os.environ["EXPECTED_URI"]
-          actual_uri = payload.get("$id")
-          if actual_uri != expected_uri:
-              raise SystemExit(f"schema $id mismatch: got={actual_uri!r} want={expected_uri!r}")
-
-          digest = "sha256:" + hashlib.sha256(raw).hexdigest()
-          expected_digest = os.environ["EXPECTED_DIGEST"]
-          if digest != expected_digest:
-              raise SystemExit(f"schema digest mismatch: got={digest!r} want={expected_digest!r}")
+          checks = [
+              (
+                  Path("api/schema/model.schema.json"),
+                  os.environ["EXPECTED_MODEL_URI"],
+                  os.environ["EXPECTED_MODEL_DIGEST"],
+              ),
+              (
+                  Path("api/schema/snapshot.schema.json"),
+                  os.environ["EXPECTED_SNAPSHOT_URI"],
+                  os.environ["EXPECTED_SNAPSHOT_DIGEST"],
+              ),
+          ]
+
+          for schema_path, expected_uri, expected_digest in checks:
+              raw = schema_path.read_bytes()
+              payload = json.loads(raw.decode("utf-8"))
+              actual_uri = payload.get("$id")
+              if actual_uri != expected_uri:
+                  raise SystemExit(
+                      f"schema $id mismatch for {schema_path}: got={actual_uri!r} want={expected_uri!r}"
+                  )
+
+              digest = "sha256:" + hashlib.sha256(raw).hexdigest()
+              if digest != expected_digest:
+                  raise SystemExit(
+                      f"schema digest mismatch for {schema_path}: got={digest!r} want={expected_digest!r}"
+                  )
           PY
 
       - name: Build publish artifact
         shell: bash
         env:
-          SCHEMA_VERSION: ${{ steps.contract.outputs.schema_version }}
-          SCHEMA_URI: ${{ steps.contract.outputs.schema_uri }}
-          SCHEMA_DIGEST: ${{ steps.contract.outputs.schema_digest }}
+          MODEL_SCHEMA_VERSION: ${{ steps.contract.outputs.model_schema_version }}
+          MODEL_SCHEMA_URI: ${{ steps.contract.outputs.model_schema_uri }}
+          MODEL_SCHEMA_DIGEST: ${{ steps.contract.outputs.model_schema_digest }}
+          SNAPSHOT_SCHEMA_VERSION: ${{ steps.contract.outputs.snapshot_schema_version }}
+          SNAPSHOT_SCHEMA_URI: ${{ steps.contract.outputs.snapshot_schema_uri }}
+          SNAPSHOT_SCHEMA_DIGEST: ${{ steps.contract.outputs.snapshot_schema_digest }}
         run: |
           set -euo pipefail
 
           ROOT="out"
-          VERSION_DIR="${ROOT}/schema/model/v${SCHEMA_VERSION}"
-          LATEST_DIR="${ROOT}/schema/model/latest"
+          MODEL_VERSION_DIR="${ROOT}/schema/model/v${MODEL_SCHEMA_VERSION}"
+          MODEL_LATEST_DIR="${ROOT}/schema/model/latest"
+          SNAPSHOT_VERSION_DIR="${ROOT}/schema/snapshot/v${SNAPSHOT_SCHEMA_VERSION}"
+          SNAPSHOT_LATEST_DIR="${ROOT}/schema/snapshot/latest"
 
-          mkdir -p "${VERSION_DIR}" "${LATEST_DIR}" "${ROOT}/schema"
+          mkdir -p "${MODEL_VERSION_DIR}" "${MODEL_LATEST_DIR}" "${SNAPSHOT_VERSION_DIR}" "${SNAPSHOT_LATEST_DIR}" "${ROOT}/schema"
 
-          cp api/schema/model.schema.json "${VERSION_DIR}/model.schema.json"
-          cp api/schema/model.schema.json "${LATEST_DIR}/model.schema.json"
+          cp api/schema/model.schema.json "${MODEL_VERSION_DIR}/model.schema.json"
+          cp api/schema/model.schema.json "${MODEL_LATEST_DIR}/model.schema.json"
+          cp api/schema/snapshot.schema.json "${SNAPSHOT_VERSION_DIR}/snapshot.schema.json"
+          cp api/schema/snapshot.schema.json "${SNAPSHOT_LATEST_DIR}/snapshot.schema.json"
 
           UPDATED_AT="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
           cat > "${ROOT}/schema/index.json" <<EOF
           {
             "name": "io.mb3r.bering.model",
-            "version": "${SCHEMA_VERSION}",
-            "uri": "${SCHEMA_URI}",
-            "digest": "${SCHEMA_DIGEST}",
+            "version": "${MODEL_SCHEMA_VERSION}",
+            "uri": "${MODEL_SCHEMA_URI}",
+            "digest": "${MODEL_SCHEMA_DIGEST}",
+            "model": {
+              "name": "io.mb3r.bering.model",
+              "version": "${MODEL_SCHEMA_VERSION}",
+              "uri": "${MODEL_SCHEMA_URI}",
+              "digest": "${MODEL_SCHEMA_DIGEST}"
+            },
+            "snapshot": {
+              "name": "io.mb3r.bering.snapshot",
+              "version": "${SNAPSHOT_SCHEMA_VERSION}",
+              "uri": "${SNAPSHOT_SCHEMA_URI}",
+              "digest": "${SNAPSHOT_SCHEMA_DIGEST}"
+            },
+            "contracts": [
+              {
+                "name": "io.mb3r.bering.model",
+                "version": "${MODEL_SCHEMA_VERSION}",
+                "uri": "${MODEL_SCHEMA_URI}",
+                "digest": "${MODEL_SCHEMA_DIGEST}"
+              },
+              {
+                "name": "io.mb3r.bering.snapshot",
+                "version": "${SNAPSHOT_SCHEMA_VERSION}",
+                "uri": "${SNAPSHOT_SCHEMA_URI}",
+                "digest": "${SNAPSHOT_SCHEMA_DIGEST}"
+              }
+            ],
             "updated_at": "${UPDATED_AT}"
           }
           EOF

.github/workflows/release.yml

@@ -92,10 +92,10 @@ jobs:
           done
           if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
             gh release upload "${GITHUB_REF_NAME}" "${args[@]}" --clobber
-            gh release edit "${GITHUB_REF_NAME}" --title "${GITHUB_REF_NAME}" --notes-file dist/release-notes.md
+            gh release edit "${GITHUB_REF_NAME}" --title "Bering ${GITHUB_REF_NAME}" --notes-file dist/release-notes.md
           else
             gh release create "${GITHUB_REF_NAME}" \
               "${args[@]}" \
-              --title "${GITHUB_REF_NAME}" \
+              --title "Bering ${GITHUB_REF_NAME}" \
               --notes-file dist/release-notes.md
           fi

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## v0.1.0
+
+First public product release of Bering.
+
+### Highlights
+
+- Batch discovery from normalized trace input, OTEL trace input, and explicit `topology_api` inputs.
+- Artifact validation against pinned public JSON schemas.
+- Runtime service with OTLP/HTTP ingest, optional OTLP/gRPC ingest, health endpoints, Prometheus metrics, and rolling snapshot emission.
+- Discovery overlays for additive metadata such as labels, weights, predicate references, and replica overrides.
+- Example artifacts, runtime config, collector wiring, Prometheus scrape config, and Grafana dashboard checked into the repository.
+
+### Product vs schema versioning
+
+- Product release tag: `v0.1.0`
+- Public schema contracts emitted by this release remain:
+  - `io.mb3r.bering.model@1.0.0`
+  - `io.mb3r.bering.snapshot@1.0.0`
+- Schema publishing to GitHub Pages remains a separate operation under `schema-v1.0.0`
+
+### Packaging and install surface
+
+- Reproducible release archives via GoReleaser for `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, and `windows/amd64`.
+- Release payload includes checksums, SBOMs, contracts pack, OCI image metadata, Helm chart metadata, and `release-manifest.json`.
+- Explicit install path documented for release binaries, source builds, OCI image usage, Helm usage, and offline contracts pack consumption.
+
+### Sheaft integration path
+
+- The primary downstream handoff remains the stable model artifact `io.mb3r.bering.model@1.0.0`.
+- Checked-in examples and README commands show the expected handoff into Sheaft.
+
+### Known limits
+
+- Bering stops at discovery and publishing; it does not perform simulation, gating, or chaos orchestration.
+- Runtime mode intentionally keeps memory bounded to a single active tumbling window plus the previous emitted snapshot.
+- Late spans and in-memory caps are operational tradeoffs surfaced through metrics and logs, not hidden retries or buffering guarantees.