Release governance-sdk 0.13.0

- OTel conventions default flips from "both" to "gen_ai"; governance
  spans now correlate with Anthropic/OpenAI/Vercel-AI spans out of the
  box. Pass conventions: "both" to keep emitting legacy governance.*
  op names alongside.
- createMCPTrustRegistry and createChainAuditor emit a one-shot
  console.warn pointing to the honest names (createMCPAllowlist,
  createMCPCallRecorder). Refactored internals into buildAllowlist /
  buildCallRecorder so the honest names don't re-trigger the warning.
- 1,340 tests, 0 failures (3 new tests pin the 0.13 OTel default).

Both changes were promised in the 0.12 CHANGELOG.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: scotty595

packages/governance/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [0.13.0] - 2026-04-16 — Conventions flip + deprecation notices
+
+Follow-up to 0.12. Two small, deliberate changes that the 0.12 roadmap
+promised — committed now so users have runtime notice before 1.0.
+
+### Changed — OTel `conventions` default flips from `"both"` to `"gen_ai"`
+
+`createOtelHooks()` now defaults to emitting only the GenAI semantic
+conventions. Governance spans correlate out of the box with Anthropic,
+OpenAI, and Vercel-AI SDK spans in Honeycomb / Datadog / New Relic when
+you ingest them through the same tracer.
+
+**Migration.** If your dashboards query the legacy `governance.*`
+operation names (`governance.enforcement`, `governance.audit`, etc.),
+set `conventions: "both"` explicitly:
+
+```ts
+createOtelHooks({ conventions: "both" });
+```
+
+This keeps the old op names alongside the new `gen_ai.*` attributes,
+same as the 0.12 default. `conventions: "governance"` disables GenAI
+emission entirely for customers who cannot adopt the spec yet.
+
+### Changed — `createMCPTrustRegistry` and `createChainAuditor` now warn
+
+Both of these names misrepresented what the functions do. The honest
+names (`createMCPAllowlist` and `createMCPCallRecorder`) shipped in
+0.12 as path re-exports, and 0.13 adds a one-shot `console.warn` when
+the old names are called so you see the nudge at runtime, once per
+process.
+
+- `createMCPTrustRegistry` → rename to `createMCPAllowlist`
+  (path: `governance-sdk/plugins/mcp-allowlist`)
+- `createChainAuditor` → rename to `createMCPCallRecorder`
+  (path: `governance-sdk/plugins/mcp-call-recorder`)
+
+Removal is scheduled for 1.0. Behaviour is identical across both
+names — the internals were refactored into a shared `buildAllowlist` /
+`buildCallRecorder` so the honest names call the core directly and
+don't trigger the deprecation path.
+
+### Tests
+
+1,340 tests, 0 failures (up from 1,337 — three new tests pinning the
+0.13 OTel default).
+
+### Roadmap (0.14+)
+
+Unchanged from the 0.12 CHANGELOG:
+- Multi-modal input scanning (image / PDF / audio) on Anthropic /
+  Vercel AI / Bedrock / Genkit / LlamaIndex.
+- Signed compliance evidence export (EU AI Act + NIST AI RMF).
+
 ## [0.12.0] - 2026-04-16 — Trust hardening
 
 Closes the three most load-bearing honesty gaps surfaced by the post-0.11

packages/governance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "governance-sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "AI Agent Governance for TypeScript — policy enforcement, scoring, compliance, and audit for AI agents",
   "type": "module",
   "main": "./dist/index.js",

packages/governance/src/otel-hooks.test.ts

@@ -10,7 +10,9 @@ describe("OTel Hooks", () => {
   });
 
   it("converts governance event to span", () => {
-    const hooks = createOtelHooks();
+    // Pin conventions: "both" because this test predates the 0.13 default
+    // flip and asserts the legacy `governance.*` operation name + attrs.
+    const hooks = createOtelHooks({ conventions: "both" });
     const span = hooks.toSpan({
       type: "enforcement",
       timestamp: new Date().toISOString(),
@@ -55,7 +57,7 @@ describe("OTel Hooks", () => {
   });
 
   it("creates enforcement span via convenience method", () => {
-    const hooks = createOtelHooks();
+    const hooks = createOtelHooks({ conventions: "both" });
     const span = hooks.enforcementSpan({
       blocked: false,
       outcome: "allow",
@@ -69,7 +71,7 @@ describe("OTel Hooks", () => {
   });
 
   it("handles missing optional fields gracefully", () => {
-    const hooks = createOtelHooks();
+    const hooks = createOtelHooks({ conventions: "both" });
     const span = hooks.toSpan({ type: "audit", timestamp: new Date().toISOString(), detail: {} });
     assert.equal(span.operationName, "governance.audit");
     assert.ok(!("governance.agent.id" in span.attributes));
@@ -84,6 +86,38 @@ describe("OTel Hooks", () => {
   });
 });
 
+describe("OTel defaults (0.13)", () => {
+  it("defaults to gen_ai conventions for events with a GenAI analogue", () => {
+    const hooks = createOtelHooks();
+    const span = hooks.toSpan({
+      type: "enforcement",
+      timestamp: new Date().toISOString(),
+      detail: { blocked: false, outcome: "allow" },
+    });
+    assert.equal(span.operationName, "gen_ai.policy.evaluate");
+  });
+
+  it("defaults to gen_ai: audit events use gen_ai.audit.log, not governance.audit", () => {
+    const hooks = createOtelHooks();
+    const span = hooks.toSpan({
+      type: "audit",
+      timestamp: new Date().toISOString(),
+      detail: {},
+    });
+    assert.equal(span.operationName, "gen_ai.audit.log");
+  });
+
+  it("defaults to gen_ai: events with no GenAI analogue still use governance.*", () => {
+    const hooks = createOtelHooks();
+    const span = hooks.toSpan({
+      type: "kill",
+      timestamp: new Date().toISOString(),
+      detail: { reason: "emergency" },
+    });
+    assert.equal(span.operationName, "governance.kill");
+  });
+});
+
 describe("OTel GenAI semantic conventions (0.12)", () => {
   it("emits gen_ai.* attributes when conventions: 'gen_ai'", () => {
     const hooks = createOtelHooks({ conventions: "gen_ai" });

packages/governance/src/otel-hooks.ts

@@ -4,14 +4,13 @@
  * Produces structured span-compatible data from governance events.
  * Zero dependencies — outputs plain objects that users wire to their OTel tracer.
  *
- * Since 0.12, `createOtelHooks({ conventions })` can emit attributes using:
+ * Since 0.13, `createOtelHooks({ conventions })` defaults to "gen_ai" so
+ * governance spans correlate out of the box with Anthropic / OpenAI /
+ * Vercel-AI SDK spans in Honeycomb / Datadog / New Relic. Options:
  *   - "governance" — legacy `governance.*` namespace (pre-0.12 default)
- *   - "gen_ai"     — OpenTelemetry GenAI semantic conventions (recommended
- *                    going forward — correlates with spans emitted by the
- *                    Anthropic / OpenAI / Vercel-AI SDKs when they adopt
- *                    the same conventions)
- *   - "both"       — emit both; current default for 0.12, flips to
- *                    "gen_ai" in 0.13
+ *   - "gen_ai"     — OpenTelemetry GenAI semantic conventions (0.13 default)
+ *   - "both"       — emit both; pin this if you have dashboards that query
+ *                    the legacy `governance.*` operation names
  *
  * GenAI spec: https://opentelemetry.io/docs/specs/semconv/gen-ai/
  *
@@ -56,8 +55,9 @@ export interface OtelHooksConfig {
   /** Service name for span attributes (default: "governance-sdk") */
   serviceName?: string;
   /**
-   * Which attribute namespace to emit. Default: "both" in 0.12 for smooth
-   * migration. Flips to "gen_ai" in 0.13. Set explicitly to pin behaviour.
+   * Which attribute namespace to emit. Default "gen_ai" from 0.13 onward.
+   * Pass "both" to additionally emit the legacy `governance.*` namespace
+   * or "governance" to fully disable gen_ai.* output.
    */
   conventions?: OtelConventions;
   /** Custom attribute mapper — runs after built-in mapping. */
@@ -153,7 +153,10 @@ function addGovernanceAttributes(
 
 export function createOtelHooks(config: OtelHooksConfig = {}) {
   const serviceName = config.serviceName ?? "governance-sdk";
-  const conventions = config.conventions ?? "both";
+  // Default flipped from "both" → "gen_ai" in 0.13 per the 0.12 roadmap.
+  // Back-compat: set `conventions: "both"` to keep emitting legacy
+  // governance.* operation names alongside the new gen_ai.* ones.
+  const conventions = config.conventions ?? "gen_ai";
 
   return {
     /**

packages/governance/src/plugins/mcp-call-recorder.ts

@@ -16,7 +16,7 @@
  * ```
  */
 export {
-  createChainAuditor as createMCPCallRecorder,
+  createMCPCallRecorder,
   createChainAuditor,
   type ChainEntry,
   type ChainEntry as MCPCallRecord,

packages/governance/src/plugins/mcp-chain-audit.ts

@@ -55,7 +55,35 @@ export interface PatternMatch {
 
 // ─── Implementation ─────────────────────────────────────────
 
+let chainAuditorDeprecationWarned = false;
+
+/**
+ * Deprecated since 0.12, removed in 1.0. Prefer `createMCPCallRecorder`
+ * (same behaviour, honest name — records caller-reported MCP calls, does
+ * not auto-propagate across MCP server boundaries).
+ */
 export function createChainAuditor(config: ChainAuditConfig = {}) {
+  if (!chainAuditorDeprecationWarned) {
+    chainAuditorDeprecationWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[governance-sdk] createChainAuditor is deprecated since 0.12 — it is a caller-instrumented call recorder, not an automatic sub-call propagator. " +
+        "Rename to createMCPCallRecorder (import path: governance-sdk/plugins/mcp-call-recorder). " +
+        "The old name will be removed in 1.0.",
+    );
+  }
+  return buildCallRecorder(config);
+}
+
+/**
+ * The honest name. Identical behaviour to `createChainAuditor` without the
+ * deprecation warning. Use this in all new code.
+ */
+export function createMCPCallRecorder(config: ChainAuditConfig = {}) {
+  return buildCallRecorder(config);
+}
+
+function buildCallRecorder(config: ChainAuditConfig = {}) {
   const { maxChainLength = 50 } = config;
   const chains = new Map<string, ChainEntry[]>();
   const patterns = config.suspiciousPatterns ?? getDefaultPatterns();

packages/governance/src/plugins/mcp-trust.ts

@@ -54,7 +54,34 @@ export interface MCPTrustValidation {
 
 // ─── Implementation ─────────────────────────────────────────
 
+let trustRegistryDeprecationWarned = false;
+
+/**
+ * Deprecated since 0.12, removed in 1.0. Prefer `createMCPAllowlist`
+ * (same behaviour, honest name).
+ */
 export function createMCPTrustRegistry(config: MCPTrustConfig = {}) {
+  if (!trustRegistryDeprecationWarned) {
+    trustRegistryDeprecationWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[governance-sdk] createMCPTrustRegistry is deprecated since 0.12 — it is a URI allowlist, not a cryptographic trust registry. " +
+        "Rename to createMCPAllowlist (import path: governance-sdk/plugins/mcp-allowlist). " +
+        "The old name will be removed in 1.0.",
+    );
+  }
+  return buildAllowlist(config);
+}
+
+/**
+ * The honest name. Identical behaviour to `createMCPTrustRegistry` without
+ * the deprecation warning. Use this in all new code.
+ */
+export function createMCPAllowlist(config: MCPTrustConfig = {}) {
+  return buildAllowlist(config);
+}
+
+function buildAllowlist(config: MCPTrustConfig = {}) {
   const { defaultTrust = "untrusted", blockUntrusted = false } = config;
   const registry = new Map<string, MCPServerEntry>();
 
@@ -144,13 +171,14 @@ function normalizeUri(uri: string): string {
   return uri.toLowerCase().replace(/\/+$/, "");
 }
 
-// ─── Honest-naming aliases (0.12) ───────────────────────────
+// ─── Honest-naming type aliases (0.12) ───────────────────────
 //
 // `createMCPTrustRegistry` is an allowlist — not a cryptographic trust
-// registry. The honest name is exported alongside so new code can adopt
-// it; the original export stays for backwards compatibility. The path
-// /plugins/mcp-allowlist in package.json exports re-exports these.
-export const createMCPAllowlist = createMCPTrustRegistry;
+// registry. The honest name `createMCPAllowlist` is defined above; these
+// are the matching type aliases so TypeScript users can write
+// `const gate: MCPAllowlistValidation = ...` without reaching back into
+// the legacy `MCPTrust*` names. The path /plugins/mcp-allowlist in
+// package.json exports re-exports these.
 export type MCPAllowlistLevel = MCPTrustLevel;
 export type MCPAllowlistConfig = MCPTrustConfig;
 export type MCPAllowlistEntry = MCPServerEntry;