docs(versioning): add VERSIONING.md reconciling artifact versions

[surpradhan]

What does this PR do?

Adds a root VERSIONING.md — the single page reconciling AEP's independently-versioned artifacts (protocol specversion 0.2.0 · HTTP API v1 · server package 1.0.0 (unreleased, run-from-source) · Python SDK on PyPI · Node SDK 0.4.0 on npm · Go SDK sdks/go/v0.3.0 · audit bundle 0.1.0), what each number versions, why they differ, and the per-artifact release mechanics. Adds one row linking it from README's documentation table.

Why?

The 2026-07-19 CTO review found five artifacts telling five maturity stories with no reconciliation anywhere — e.g. the server's 1.0.0 implies a released product while no server release pipeline exists. (The companion fix to the internal roadmap doc's wrong "Node SDK 1.0.0 on npm" claim was applied locally — planning/ is gitignored.)

How to test?

Read it; every version claim is verifiable in-repo (package.json, sdks/*/pyproject.toml|package.json, git tags, .github/workflows/release-*.yml).

Related Issues

CTO review Wave 1, item 6.

Checklist

• Docs only, no code changes
• All version claims verified against source

🤖 Generated with Claude Code

[surpradhan]

Independent review — PR #161 (docs: VERSIONING.md)

Reviewed against the repo at e169d06 (worktree rebased on main). Every factual claim in VERSIONING.md was checked against source, git tags, the three release workflow YAMLs, and the live registries.

Findings

1. Suggestion — VERSIONING.md:31-32 — "human-approved workflows" is wrong for Go and contradicts this doc's own Release-mechanics section.
The bullet says SDK versions are "released via tag-triggered, human-approved workflows (.github/workflows/release-{python,node,go}-sdk.yml)". Verified in the YAML: release-python-sdk.yml and release-node-sdk.yml each have a publish job gated by an Environment with required reviewers (pypi-publish / npm-publish), but release-go-sdk.yml has only a verify job with no environment: gate — no human approval anywhere, and the Go module proxy serves the tag regardless of the workflow outcome. VERSIONING.md:39-40 states this correctly ("the tag is the release (smoke-gate workflow only)"), so line 31-32 contradicts line 39-40 within the same page. Suggested fix: "…released via tag-triggered workflows — human-approved for Python and Node, verification-only for Go (.github/workflows/release-{python,node,go}-sdk.yml)."

2. Suggestion — VERSIONING.md:14 — "0.4.x on PyPI" durability with PR #160 in flight.
Accurate today (PyPI latest confirmed 0.4.1; sdks/python/pyproject.toml = 0.4.1 on this branch), and the hedge at lines 19-21 ("in-repo version may be ahead… PyPI/npm are the source of truth") correctly covers the window after #160 bumps pyproject to 0.5.0 but before a release tag ships. However, the moment python-sdk-v0.5.0 is published, "Current: 0.4.x" goes stale — and the Python row is the only row guaranteed to churn (Node/Go frozen, protocol/audit static). Two concrete options: (a) keep the number but make the registry the stated authority in the cell itself, e.g. "0.4.x — latest on PyPI", or (b) accept per-release doc maintenance and (in a follow-up, not this PR) add "update VERSIONING.md's Current column" to the release-cutting checklist comment in release-python-sdk.yml. Either is fine; as-written it will silently drift on the next Python release.

3. Nit — VERSIONING.md:12 — unversioned-endpoint list reads as exhaustive but omits /openapi.json and /docs.
Verified in src/server.js: the v1 router is mounted at both / (line 1908) and /v1 (line 1905), and API-Version: 1 is set globally (line 197) — all correct. But the app-level-only (unversioned) routes are /health, /ready, /metrics/prometheus, /admin/*, /dashboard(+.html), /docs, /openapi.json, and /fonts. The parenthetical omits /docs and /openapi.json. Suggested fix: add them, or soften to "infra/docs endpoints (e.g. /health, /ready, /metrics/prometheus, /admin/*, /dashboard, /openapi.json)".

Verified correct (no action)

• Root package.json = 1.0.0; no server/operator/otelbridge publish workflow exists (.github/workflows/ = ci.yml + 3 SDK release files only); operator/ and otelbridge/ directories both exist, so naming them is right.
• specversion 0.2.0: envelope schema pattern-locks it (schemas/aep-envelope.schema.json), 20 fixture/schema occurrences all 0.2.0 (the lone "1.0" is the deliberate tests/fixtures/invalid/bad-specversion.json); 12 core event types exactly match aep-core-events.schema.json; 0.2.0 landed 2026-03-22 (CHANGELOG), predating every SDK release tag — "stable across every release" holds.
• Node SDK 0.4.0: sdks/node/package.json = 0.4.0, npm view @surpradhan/aep version = 0.4.0, tag node-sdk-v0.4.0 exists.
• Go: tag sdks/go/v0.3.0 exists; go get github.com/surpradhan/agent-event-protocol/sdks/go matches sdks/go/go.mod module path.
• Audit bundle 0.1.0: src/audit.js AUDIT_VERSION = "0.1.0"; aep audit export CLI and both audit-bundle endpoints exist as described.
• Python/Node release mechanics (verify job with tag-on-main ancestry check → environment-gated publish; npm publish --provenance; PyPI Trusted Publishing/OIDC) match the YAML exactly.
• Tone matches README's direction note ("reference implementation", OTel convergence); README table row renders correctly and matches house style; links resolve (README.md relative-from-root, PyPI and npm pages live); no planning/ links crept in.
• Gates green on the branch: lint clean, 494 unit + 264 integration tests pass.

Verdict: Request Changes — one one-line factual fix (finding 1); findings 2–3 are polish. After finding 1 is fixed this is an easy approve: the page does exactly what it promises and every number in it is real.

[surpradhan]

Independent validation review (validator context, not the author)

Verdict: Approve — docs-only PR; every load-bearing version claim was verified empirically against the repo, live registries, and a running server. Zero actionable items.

Scope

gh pr diff 161 --name-only = README.md + VERSIONING.md only (+45/-0). Worktree diff matches the PR diff exactly; no uncommitted work.

Gates (run in the PR worktree)

• npm test: 494 unit + 264 integration, 0 fail
• npm run lint: clean
• CI: 14/14 checks pass, including the Required checks in sync drift guard.

Claim-by-claim probes (all confirmed)

Claim in VERSIONING.md	Evidence
Protocol specversion 0.2.0	schemas/aep-envelope.schema.json pattern ^0\.2\.0$; schema untouched since it landed (git log)
HTTP API v1: /v1 prefix + API-Version: 1 header	Live boot: GET /v1/sessions unauth -> 401 with API-Version: 1; GET /sessions (unversioned mount) -> same 401 + header
Infra endpoints unversioned by design	/health, /ready, /dashboard, /metrics/prometheus are app-level in src/server.js (310/335/399/1343); live GET /v1/health -> 404, GET /health -> 200 reporting version: 1.0.0
Server package 1.0.0, not released anywhere	root package.json = 1.0.0; .github/workflows/ contains only ci.yml + 3 release-*-sdk.yml; ci.yml docker job builds without any registry login/push
Python SDK 0.4.x on PyPI as agent-event-protocol	pyproject 0.4.1; latest tag python-sdk-v0.4.1; PyPI live: 0.4.1
Node SDK 0.4.0 on npm as @surpradhan/aep	sdks/node/package.json = 0.4.0; npm live dist-tag: 0.4.0
Go SDK sdks/go/v0.3.0, module path	latest go tag is sdks/go/v0.3.0; go.mod module = github.com/surpradhan/agent-event-protocol/sdks/go
Audit bundle 0.1.0	src/audit.js:47 AUDIT_VERSION = "0.1.0"
Release mechanics (Py: tag-on-main verify -> gated OIDC; Node: gated npm publish --provenance; Go: ancestry+build+test smoke gate only)	verified line-by-line in the three release workflows
operator/otelbridge exist, no release pipeline	both directories present; no matching workflow
README direction note referenced for maintenance-mode SDKs	present at README.md top (2026-06 direction note)

Markdown checks

• Table column counts consistent in both files (checked programmatically).
• All relative links resolve (./VERSIONING.md from README, README.md from VERSIONING.md); no links into gitignored planning/.

Non-blocking observation

The pinned "Current" values for Node (0.4.0) and Go (v0.3.0) will need a touch-up on each SDK release; the page already hedges with "PyPI/npm are the source of truth", so this is acceptable drift risk for a reconciliation doc, not a change request.

[surpradhan]

Round-1 findings applied in b002929: (1) the 'Why they differ' bullet now states the gating accurately — human-approved publish for Python/Node, verification-only for Go where the tag is the release; (2) the Python cell defers to PyPI as the authority ('latest on PyPI, 0.4.x at time of writing') so it doesn't rot per release; (3) the unversioned-endpoints list is 'e.g.'-prefixed and includes /docs and /openapi.json.

[surpradhan]

Round-2 review (delta e169d06..b002929) — APPROVE

Narrow re-review of the round-1 findings. All three are verified fixed against the actual sources; no new inaccuracy or self-contradiction introduced.

S1 (Go "human-approved workflows" claim) — FIXED. The gating bullet now reads "human-approved publish gate for Python and Node, and verification-only for Go, where the tag itself is the release." Verified against all three workflows:

• release-python-sdk.yml: gated publish job, environment: pypi-publish (required reviewers) — human-approved. ✓
• release-node-sdk.yml: gated publish job, environment: npm-publish — human-approved. ✓
• release-go-sdk.yml: single verify job (ancestry + build + test), no publish step; its own header states "this workflow does not publish anything; it is a verification gate" and "a Go module is 'released' purely by pushing a Git tag." ✓
  The bullet's "(see Release mechanics below)" cross-reference is consistent with that section's per-language bullets (Python "human-gated", Node "same gate", Go "the tag is the release (smoke-gate workflow only)"). No contradiction.

S2 (Python "0.4.x" cell durability) — FIXED. Cell now says "latest on PyPI … (0.4.x at time of writing)" with "the registry is the authority; this cell is not updated per release." Checked live: PyPI latest for agent-event-protocol is 0.4.1, and in-repo sdks/python/pyproject.toml is 0.4.1 — "0.4.x at time of writing" is accurate, and the cell no longer decays into a false claim on the next release. Consistent with the existing "PyPI/npm are the source of truth" paragraph below the table.

N3 (unversioned-endpoint list) — FIXED. List is now "e.g."-prefixed (no exhaustiveness claim) and includes /docs + /openapi.json. Verified every listed endpoint is mounted directly on app, not the v1 router: /health (src/server.js:310), /ready (:335), /metrics/prometheus (:1343), /dashboard (:399), /docs (:369), /openapi.json (:359), admin routes per the :203-204 mounting comment. The reworded "app-level endpoints" is apt — it matches the implementation (served at app level rather than on the versioned router) and now correctly covers the non-infra entries (/docs, /dashboard, /openapi.json) that "infra endpoints" did not.

Table rendering: all 9 table lines (header + delimiter + 7 data rows) have exactly 4 cells; no unescaped pipes inside cells. Renders correctly.

Gates: docs-only delta; CI green on the head commit (one matrix job still finishing at time of review).

Zero actionable items. Verdict: Approve.

[surpradhan]

Validator round 2 (delta e169d06..b002929) — VALIDATED, Approve stands

Narrow re-validation of the review-fix commit b002929. Round-1 verdict was Approve / zero actionable; this pass checks only the delta and re-confirms CI.

1. Diff scope — git diff e169d06..b002929: touches only VERSIONING.md (+6/-4), and the changes are exactly the three review findings:

• Go gating wording: "human-approved publish gate for Python and Node, and verification-only for Go, where the tag itself is the release"
• Python SDK cell made registry-authoritative: "latest on PyPI … (0.4.x at time of writing) … the registry is the authority; this cell is not updated per release"
• Endpoint list now e.g.-prefixed and includes /docs + /openapi.json (cell renamed infra → app-level, which fits the additions)

2. Factual probes against the workflows/code

• release-go-sdk.yml: no environment: key anywhere; the single verify job does ancestry-check + build + test and publishes nothing (header comment says the same). "Verification-only, tag is the release" is accurate. ✓
• release-python-sdk.yml:159 environment: pypi-publish and release-node-sdk.yml:124 environment: npm-publish — human-approved publish gates present for both, matching the new wording. ✓
• src/server.js: GET /openapi.json (line 359) and GET /docs (line 369) are app-level routes registered before the /v1 router mount (line 1905), i.e. genuinely unversioned by design. ✓
• PyPI live check: latest agent-event-protocol is 0.4.1, in-repo pyproject.toml is 0.4.1 — "0.4.x at time of writing" is correct, and the registry-authoritative phrasing means the cell stays true when 0.4.2 ships. ✓

3. Table integrity — all 9 table lines (header, separator, 7 rows) have exactly 5 pipes / 4 columns; renders consistently. ✓

4. CI — all 14/14 checks green on head b002929 (watched to completion: test 20.x, Node SDK 20/22, Go SDK, Python SDK 3.10–3.13, Operator, Postgres parity, otelbridge, Required-checks-in-sync, build, docker). Worktree at PR head, clean, gh pr diff matches. ✓

Findings: zero actionable items.

Verdict: Approve (round-2, delta-scoped).