feat: establish explicit shared telemetry runtime and Collector canary

.github/workflows/prepare-release.yml

@@ -0,0 +1,53 @@
+name: Prepare telemetry release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cwl-telemetry-release
+  cancel-in-progress: false
+
+jobs:
+  prepare:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12.13'
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: '0.12.3'
+      - run: uv sync --locked --group dev --no-install-project
+      - run: uv sync --locked --group dev --no-build-isolation
+      - run: uv run --no-sync pytest -q
+      - run: uv build --no-build-isolation
+      - run: tar -tzf dist/*.tar.gz | grep 'collector/production.yaml$' > /dev/null
+      - name: Create reviewable draft with exact-source artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git fetch origin main
+          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+          test "$(git rev-parse origin/main)" = "$GITHUB_SHA"
+          version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          tag="v${version}"
+          if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null; then
+            echo 'Version tag already exists' >&2
+            exit 1
+          fi
+          cp collector/production.yaml dist/cwl-otelcol-production.yaml
+          (cd dist && sha256sum ./*.whl ./*.tar.gz ./cwl-otelcol-production.yaml > SHA256SUMS)
+          gh release create "$tag" dist/*.whl dist/*.tar.gz dist/cwl-otelcol-production.yaml dist/SHA256SUMS \
+            --draft --target "$GITHUB_SHA" --title "$tag" \
+            --notes 'Draft release for independent review. Verify current-head checks, artifact hashes, and consumer migration before publication.'

.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Telemetry contract
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.repository }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  contract:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12.13'
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: '0.12.3'
+      - run: uv sync --locked --group dev --no-install-project
+      - run: uv sync --locked --group dev --no-build-isolation
+      - run: uv run --no-sync pytest -q
+      - run: uv build --no-build-isolation
+      - run: tar -tzf dist/*.tar.gz | grep 'collector/production.yaml$' > /dev/null

.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.codegraph/
+.pytest_cache/
+.coverage
+*.egg-info/
+__pycache__/
+dist/
+graphify-out/

.python-version

@@ -0,0 +1 @@
+3.12.13

AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+## Repository mission
+
+`cwl-telemetry` is the optional canonical owner of the shared, explicit
+OpenTelemetry runtime, Collector routing template, normalized security-event
+receiver, and SIEM delivery contract. Product repositories retain domain
+events, authorization decisions, audit truth, credential lifecycle, and
+deployment ownership.
+
+This repository is pre-release. An open PR or passing predecessor check is
+Proposed evidence only; consumers must use a disabled feature flag or contract
+test double until a protected-main build has an immutable version and digest.
+
+## Required workflow
+
+1. Fetch the current PR head and default-branch head before changing anything.
+2. Review every open PR thread and exact-head check. Preserve concurrent work;
+   use ordinary descendant commits only—never force-push or destructively
+   rebase.
+3. Start behavioral changes with a failing test at the canonical writer.
+4. Run the smallest relevant test first, then the complete locked gate:
+   `uv sync --locked --group dev --no-install-project`,
+   `uv sync --locked --group dev --no-build-isolation`, and
+   `uv run --no-sync pytest -q`.
+5. Build with `uv build --no-build-isolation` and verify the source
+   distribution contains `collector/production.yaml`.
+6. Update `CHANGELOG.md` and
+   `docs/product-technical-gap-baseline.md` with exact revision and workflow
+   evidence. Do not convert Proposed decisions to Accepted from documentation.
+7. Keep the PR Draft until current-head Checks are terminal green and an
+   independent reviewer approves it. Merge normally; publish only from the
+   protected default branch.
+
+A hosted job with no executed steps and no log blob is runner evidence, not a
+product regression. Record its job identity and continue safe work; do not
+change source merely to retrigger infrastructure.
+
+## Ownership and dependency rules
+
+- Public product code depends only on an immutable released package or HTTPS
+  contract, never this branch, this repository's database, or copied source.
+- `security_event_outbox` is private to the receiver/sender subsystem.
+- The authenticated tenant is supplied by the receiver credential boundary,
+  never trusted from the OTLP record alone.
+- The Collector admits TLS-authenticated OTLP and separates operational from
+  normalized security records.
+- Only an exact event-ID acknowledgement marks delivery. Authenticated,
+  event-specific HTTP 400/422 rejection may quarantine; ambiguous failures stay
+  pending.
+- Never log bearer tokens, raw security records, private keys, or request
+  headers. Use synthetic credentials and events in tests.
+- Keep the runtime inert on import. Network, provider, thread, and process
+  creation require explicit bootstrap or CLI execution.
+
+## Change discipline
+
+Prefer the smallest causal change. Do not add a platform, control plane, shared
+database, UI, or new provider abstraction without measured repeated demand and
+an ADR. Preserve bounded inputs, finite vocabularies, explicit timeouts, TLS
+1.2 minimum, private regular-file checks, exact acknowledgements, and durable
+failure semantics.
+
+Public modules, classes, functions, and methods require docstrings. Tests must
+cover hostile boundaries and failure paths, including replay, conflicting
+identity, mixed tenant, slow request, TLS failure, redirect, malformed
+acknowledgement, restart, capacity exhaustion, and quarantine behavior.
+
+## Evidence and handoff
+
+`ARCHITECTURE.md` is the context and invariant authority.
+`docs/security-operability.md` is the operator and incident authority.
+`docs/product-technical-gap-baseline.md` is the live PRD/TRD/Gap status.
+`CLAUDE.md` is a concise entry point and must not duplicate these contracts.

ARCHITECTURE.md

@@ -0,0 +1,92 @@
+# Architecture
+
+Status: Proposed while PR #1 remains unmerged and unreleased.
+
+## Responsibility boundary
+
+The Telemetry subdomain contains four bounded contexts:
+
+| Bounded context | Responsibility | Owned interface/data |
+| --- | --- | --- |
+| Runtime Bootstrap | Explicit, inert SDK configuration and bounded product-facing Ports | `TelemetryConfig`, `TelemetryEvent`, `TelemetryRuntime` |
+| Signal Routing | Authenticated OTLP admission and operational/security separation | `collector/production.yaml` |
+| Security Normalization | Tenant-bound schema-v1 validation and durable idempotent admission | HTTPS `/v1/logs`; private `security_event_outbox` |
+| Security Delivery | Bounded handoff to an operator-approved SIEM gateway | HTTPS `/v1/security-events`; exact acknowledgement |
+
+Product bounded contexts are upstream customers. They own Ubiquitous Language,
+domain event truth, authorization, authoritative audit records, and retention
+decisions. This repository supplies an Anti-Corruption Layer to OpenTelemetry
+and SIEM protocols; transport never becomes product truth.
+
+## Context map
+
+```mermaid
+flowchart TD
+    Product["Product context"] -->|released SDK Port| Runtime["Runtime Bootstrap"]
+    Runtime -->|authenticated OTLP| Router["Signal Routing"]
+    Router -->|schema-v1 security logs| Normalizer["Security Normalization"]
+    Normalizer -->|private durable rows| Delivery["Security Delivery"]
+    Delivery -->|approved HTTPS contract| SIEM["SIEM gateway"]
+```
+
+No consumer may read the outbox, import a temporary branch, or share Collector
+credentials. Before an immutable release, consumers use a disabled feature flag
+or a contract test double.
+
+## Domain model and invariants
+
+- `TelemetryConfig` is a validated Value Object. Receiver configuration is
+  HTTPS-only, bearer-authenticated, and bounded.
+- `TelemetryEvent` is a product-facing Value Object with finite names,
+  purposes, classifications, kinds, and attributes.
+- A normalized security event is the aggregate admitted under one
+  authenticated tenant and one stable event ID.
+- `security_event_outbox` is the aggregate store. State 0 is pending, state 1
+  is exactly acknowledged, and state 2 is quarantined after an authenticated
+  event-specific permanent rejection.
+- Equal retries are idempotent. Reuse of an event ID with different content is
+  rejected.
+- Ambiguous network, TLS, redirect, HTTP, or acknowledgement failure cannot
+  advance delivery state.
+- Importing `cwl_telemetry` creates no provider, thread, socket, or process.
+- All wire inputs, queues, label vocabularies, batches, counters, request
+  bodies, and deadlines are bounded.
+
+SQLite is deliberately private and minimal. The receiver and scheduled sender
+are the only writers. If measured concurrency outgrows this boundary, first
+scale one receiver/outbox per tenant; adopt a new durable service only through
+an ADR and migration contract.
+
+## Runtime and deployment topology
+
+The product explicitly creates isolated providers. The Collector receives OTLP
+over TLS with bearer authentication, routes operational logs/traces/metrics to
+the configured backend, and serializes security records to the tenant-bound
+normalizer. The normalizer commits before acknowledging the Collector. A
+separate operator-scheduled sender attempts one bounded batch and marks only
+exactly acknowledged rows delivered.
+
+The production template requires a persistent `/var/lib/otelcol` volume and
+mounted credentials. Backend and security-consumer destinations are deployment
+inputs; template presence is not proof that either destination is safe or
+deployed.
+
+## Failure scenes
+
+| Scene | Required behavior |
+| --- | --- |
+| SDK exporter unavailable | Product work continues; bounded drop/failure accounting remains observable |
+| Collector restarts | Persistent queue recovers without route mixing |
+| Receiver sees a slow or malformed client | One absolute request deadline and bounded body fail closed |
+| Duplicate event arrives | Equal content is replay-safe; conflicting content is rejected |
+| SIEM is unavailable or redirects | Row remains pending and credential is not forwarded |
+| SIEM rejects one event with exact 400/422 document | Row becomes quarantined; later rows may proceed; exit status requires operator attention |
+| Process stops after remote acceptance but before local mark | Idempotency key permits safe replay |
+| Outbox reaches capacity | Receiver returns unavailable; no record is silently overwritten |
+
+## Release boundary
+
+Acceptance requires terminal exact-head contract/security checks, independent
+approval, normal merge to protected `main`, immutable artifacts and hashes,
+and a consumer parity test against the released interface. Local builds,
+predecessor checks, Draft releases, or branch URLs do not satisfy this boundary.

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this unreleased package are recorded here.
+
+## Unreleased
+
+### Added
+
+- Add contributor, architecture, and security/operability continuation guides
+  that preserve the telemetry owner boundary, exact-head evidence rules, and
+  fail-closed recovery procedures.
+
+### Fixed
+
+- Prevent reserved security event names from bypassing the durable security
+  route and export the same immutable attribute snapshot that admission checked.
+- Make trace sampling and span limits explicit, and reject an ambient global SDK
+  disable instead of silently returning a no-op runtime.
+- Match inbound W3C `traceparent` field names without case sensitivity and
+  reject ambiguous duplicates.
+- Require an exact event-bound JSON Boolean rejection before quarantine and
+  count pending plus quarantined rows against the same outbox capacity.
+- Reject operational event names longer than 128 characters before export.
+- Bound trace and log exports to 16 records and remove inherited baggage and
+  TraceState so worst-case admitted batches fit the production Collector's
+  65,536-byte ingress limit while preserving trace identity.
+- Reject counter increments whose cumulative canonical label-series total would
+  exceed the nonnegative signed 64-bit OTLP wire range; repeated handles share
+  the same synchronized accounting.

CLAUDE.md

@@ -0,0 +1,18 @@
+# CLAUDE.md
+
+Read and follow `AGENTS.md` before changing this repository.
+
+The authoritative continuation order is:
+
+1. `docs/product-technical-gap-baseline.md` for PRD/TRD, exact evidence, and
+   open commercialization Gaps;
+2. `ARCHITECTURE.md` for bounded contexts, ports, owned data, and invariants;
+3. `docs/security-operability.md` for deployment, recovery, and incident
+   procedures;
+4. the current PR head, review threads, and workflow jobs for live state.
+
+Do not treat this pre-release branch as a dependency. Do not force-push, copy
+the source into consumers, read the private outbox cross-service, or claim a
+release/deployment from local tests. Behavioral work begins with a failing
+test; documentation-only work must still reconcile the live baseline and
+CHANGELOG.

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include collector *.yaml