@axiastudio/aioc 0.2.3 → 0.2.4

package/README.md

@@ -1,14 +1,29 @@
 # @axiastudio/aioc
 
-AIOC is a governance-first SDK for LLM agents: models can propose actions, while deterministic policies and runtime controls enforce decisions.
-It provides default-deny gates for tools and handoffs, end-to-end auditability (run records, prompt snapshots, request fingerprints), and a foundation for verifiable iteration on prompts and policies.
-AIOC is designed for enterprise and public-sector contexts with privacy-by-design and high-accountability (AI Act-style) governance requirements.
+AIOC is a deterministic governance kernel for LLM agents: models can propose actions, while application-owned policies and runtime controls decide what is actually allowed to happen.
+It is built around default-deny gates for tools and handoffs, portable audit artifacts (`RunRecord`, prompt snapshots, request fingerprints), and replay/compare workflows for verifiable iteration on prompts and policies.
+AIOC is designed for enterprise and public-sector contexts where governance cannot be outsourced to an observability dashboard, hosted trace store, or framework-owned approval workflow.
 
 Project home and documentation: [https://axiastudio.github.io/aioc](https://axiastudio.github.io/aioc)
 
+## Positioning
+
+AIOC does not try to be a full agent platform, hosted tracing product, evaluation suite, or human-review workflow engine.
+Those systems are useful, but they make governance-sensitive decisions about storage, retention, access, escalation, and audit semantics.
+
+AIOC keeps the enforcement boundary inside the application instead:
+
+- the model proposes; deterministic policy code authorizes or denies
+- execution-impacting capabilities are deny-by-default
+- audit evidence is emitted as portable records rather than owned by a required control plane
+- persistence, approvals, retention, access control, monitoring, and deployment remain host-application responsibilities
+
+In short: AIOC treats observability as evidence, not as governance itself.
+Its core job is to make agent execution boundaries explicit, testable, auditable, and hard to bypass.
+
 ## Release Status
 
-Current stable release: `0.2.3`.
+Current stable release: `0.2.4`.
 The stable line started with `0.1.0`.
 The core runtime surface is compatibility-managed. Breaking changes to the stable surface should ship only with explicit migration guidance and release notes.
 
@@ -22,6 +37,17 @@ AIOC `0.2.0` adds implemented runtime utilities and the Agent Harness Descriptor
 AIOC `0.2.1` realigns the `0.2.x` package line with the current `main` history after `0.2.0` was published from the descriptor release branch.
 AIOC `0.2.2` completes the descriptor instruction-composition surface with reusable `instruction_parts`, ordered `instructions_sequence`, and boolean `where` gates.
 AIOC `0.2.3` adds RFC-0010 policy composition helpers for exact-name tool and handoff policy dispatch without changing runtime enforcement semantics.
+AIOC `0.2.4` adds experimental governance-event packages and an OpenTelemetry Logs exporter for reduced, operational observability events derived from `RunRecord` values.
+
+### Experimental Packages
+
+`@axiastudio/aioc-governance-events` implements the RFC-0009 governance-event
+mapper outside the core runtime package. It derives reduced, redacted,
+event-shaped records from `RunRecord` values.
+
+`@axiastudio/aioc-export-otel` maps those governance events to OpenTelemetry
+Logs. Both packages remain experimental while real exporter usage validates the
+schema and operational shape.
 
 - Release notes: `CHANGELOG.md`
 - Historical beta contract snapshot: `docs/BETA-CONTRACT.md`
@@ -243,6 +269,7 @@ This repository also contains `aioc-inspect`, a private reference example UI for
 | `npm run example:approval-required` | Minimal approval-required tool + policy flow | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:approval-evidence` | Approval evidence passed through context and reevaluated by policy | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:tool-policy` | Straight tool + policy flow with allowed execution | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
+| `npm run example:policy-composition` | Exact-name tool policy dispatch with fallback deny | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:run-record` | Run-record persistence with redaction + audit | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:rru:01-extract` | Minimal `extractToolCalls(...)` | No |
 | `npm run example:rru:02-compare` | Minimal `compareRunRecords(...)` | No |

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@axiastudio/aioc",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "test": "npm run test:ci",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -22,6 +25,7 @@
     "example:approval-required": "tsx src/examples/basic/approval-required.ts",
     "example:approval-evidence": "tsx src/examples/basic/approval-evidence.ts",
     "example:tool-policy": "tsx src/examples/basic/tools.ts",
+    "example:policy-composition": "tsx src/examples/basic/policy-composition.ts",
     "example:harness": "tsx src/examples/harness-descriptor/customer-support.ts",
     "example:run-record": "tsx src/examples/basic/run-record-sink.ts",
     "example:rru:01-extract": "tsx src/examples/run-record-utils-minimal/01-extract-tool-calls.ts",
@@ -34,6 +38,14 @@
     "docs:dev": "npm run docs:sync && cd apps/aioc-docs && zsh -lc 'npm run dev'",
     "docs:build": "npm run docs:sync && cd apps/aioc-docs && zsh -lc 'npm run build'",
     "docs:preview": "cd apps/aioc-docs && zsh -lc 'npm run preview'",
+    "packages:build": "npm run governance-events:build && npm run build -w @axiastudio/aioc-export-otel && npm run build -w @axiastudio/aioc-inspect-ui",
+    "packages:test": "npm run governance-events:test && npm run export-otel:test",
+    "governance-events:build": "npm run build && npm run build -w @axiastudio/aioc-governance-events",
+    "governance-events:test": "npm run build && npm test -w @axiastudio/aioc-governance-events",
+    "export-otel:build": "npm run governance-events:build && npm run build -w @axiastudio/aioc-export-otel",
+    "export-otel:test": "npm run governance-events:build && npm test -w @axiastudio/aioc-export-otel",
+    "export-otel:console": "npm run governance-events:build && npm run console -w @axiastudio/aioc-export-otel",
+    "export-otel:signoz": "npm run governance-events:build && npm run signoz -w @axiastudio/aioc-export-otel",
     "test:mistral": "tsx src/examples/mistral-smoke.ts",
     "prepack": "npm run build:package"
   },