@peac/adapter-runtime-governance 0.12.9 → 0.12.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +66 -35
  2. package/package.json +6 -4
package/README.md CHANGED
@@ -1,41 +1,26 @@
1
1
  # @peac/adapter-runtime-governance
2
2
 
3
- Runtime governance adapter for PEAC interaction records. Records governance
4
- decisions, audit entries, authority scope changes, lifecycle transitions,
5
- trust signals, and compliance assessments as signed, portable Interaction
6
- Records.
3
+ Runtime governance adapter for PEAC interaction records. Records governance decisions, audit entries, authority scope changes, lifecycle transitions, trust signals, and compliance assessments as signed, portable Interaction Records.
7
4
 
8
- PEAC validates the structure and signature of the PEAC record, not the truth
9
- of the upstream governance decision or the operating effectiveness of the
10
- upstream control plane. PEAC does not verify upstream Merkle chain integrity
11
- or ML-DSA-65 signatures.
5
+ ## Installation
12
6
 
13
- ## Architecture
7
+ ```bash
8
+ pnpm add @peac/adapter-runtime-governance
9
+ ```
10
+
11
+ ## What It Does
14
12
 
15
- Generic runtime-governance surface with source-specific mappers.
16
- Microsoft AGT is the first mapper; the architecture supports additional
17
- mappers for other runtimes.
13
+ `@peac/adapter-runtime-governance` is a Layer 4 adapter that records runtime governance artifacts as signed, portable Interaction Records. It provides a generic runtime-governance surface with source-specific mappers. Microsoft AGT is the first mapper; the architecture supports additional mappers for other runtimes.
18
14
 
19
- ## Record families
15
+ PEAC validates the structure and signature of the PEAC record, not the truth of the upstream governance decision or the operating effectiveness of the upstream control plane. PEAC does not verify upstream Merkle chain integrity or ML-DSA-65 signatures.
20
16
 
21
- | Family | Type URI |
22
- | ---------------------- | ------------------------------------------------------------ |
23
- | Policy Decision | `org.peacprotocol/runtime-governance-policy-decision` |
24
- | Audit Entry | `org.peacprotocol/runtime-governance-audit-entry` |
25
- | Authority Scope | `org.peacprotocol/runtime-governance-authority-scope` |
26
- | Lifecycle Event | `org.peacprotocol/runtime-governance-lifecycle-event` |
27
- | Trust Observation | `org.peacprotocol/runtime-governance-trust-observation` |
28
- | Compliance Observation | `org.peacprotocol/runtime-governance-compliance-observation` |
17
+ ## How Do I Use It?
29
18
 
30
- ## Usage
19
+ ### Map and issue a governance record
31
20
 
32
21
  ```typescript
33
22
  import { generateKeypair, verifyLocal } from '@peac/protocol';
34
- import {
35
- issueRuntimeGovernanceRecord,
36
- mapAgtEvent,
37
- buildSessionSummary,
38
- } from '@peac/adapter-runtime-governance';
23
+ import { issueRuntimeGovernanceRecord, mapAgtEvent } from '@peac/adapter-runtime-governance';
39
24
 
40
25
  const kp = await generateKeypair();
41
26
 
@@ -52,18 +37,64 @@ const result = await issueRuntimeGovernanceRecord(event, {
52
37
  issuer: 'https://governance.example.com',
53
38
  sessionId: 'sess-001',
54
39
  agentId: 'agent-001',
55
- provider: 'example-runtime',
40
+ provider: 'example-runtime', // caller-supplied, never hardcoded
56
41
  });
57
42
 
58
43
  const verification = await verifyLocal(result.jws, kp.publicKey);
44
+ ```
45
+
46
+ ### Build a session summary
47
+
48
+ ```typescript
49
+ import { buildSessionSummary } from '@peac/adapter-runtime-governance';
50
+
59
51
  const summary = buildSessionSummary([result.jws]);
52
+ // { sessionId, receipts: 1, families: ['policy_decision'], unknownTypeCount: 0, issuer }
60
53
  ```
61
54
 
62
- ## Design constraints
55
+ `buildSessionSummary()` decodes JWS payloads to extract metadata but does **not** verify signatures. Callers must verify receipts first. Returns deterministic family ordering (sorted alphabetically) and counts unknown type URIs separately.
56
+
57
+ ## Record Families
58
+
59
+ | Family | Type URI | Kind |
60
+ | ---------------------- | ------------------------------------------------------------ | ---------- |
61
+ | Policy Decision | `org.peacprotocol/runtime-governance-policy-decision` | `evidence` |
62
+ | Audit Entry | `org.peacprotocol/runtime-governance-audit-entry` | `evidence` |
63
+ | Authority Scope | `org.peacprotocol/runtime-governance-authority-scope` | `evidence` |
64
+ | Lifecycle Event | `org.peacprotocol/runtime-governance-lifecycle-event` | `evidence` |
65
+ | Trust Observation | `org.peacprotocol/runtime-governance-trust-observation` | `evidence` |
66
+ | Compliance Observation | `org.peacprotocol/runtime-governance-compliance-observation` | `evidence` |
67
+
68
+ ## Integrates With
69
+
70
+ - `@peac/protocol` (Layer 3): Receipt issuance and local verification
71
+ - `@peac/crypto` (Layer 2): JWS decode for session summary extraction
72
+ - `@peac/adapter-managed-agents`: Managed agent event records (complementary adapter)
73
+
74
+ ## Design
75
+
76
+ - **Generic surface:** Package named by concept, not vendor. AGT is the first mapper; future mappers can be added without changing the public API.
77
+ - **Vendor-neutral:** Zero vendor SDK runtime dependencies. The `provider` field is always caller-supplied.
78
+ - **Layer 4:** Depends on `@peac/protocol` and `@peac/crypto` only.
79
+ - **Evidence kind:** All record families produce `evidence` kind Interaction Records.
80
+ - **Observational only:** PEAC records what the upstream runtime reported; PEAC does not enforce, compute, or determine.
81
+ - **Fail-closed validation:** Rejects malformed input with descriptive errors. Validates RFC 3339 timestamps, digest patterns, URI shapes, and numeric bounds.
82
+ - **Extension namespace:** `org.peacprotocol/runtime-governance` with `session_id`, `event`, `agent_id`, `provider` fields plus family-specific payload.
83
+
84
+ ## For Agent Developers
85
+
86
+ If you are building an AI agent or MCP server that needs evidence receipts:
87
+
88
+ - Start with [`@peac/mcp-server`](https://www.npmjs.com/package/@peac/mcp-server) for a ready-to-use MCP tool server
89
+ - Use `@peac/protocol` for programmatic receipt issuance and verification
90
+ - See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise overview
91
+
92
+ ## License
93
+
94
+ Apache-2.0
95
+
96
+ ---
97
+
98
+ PEAC Protocol is an open source project stewarded by Originary and community contributors.
63
99
 
64
- - Layer 4 only; no kernel/schema/crypto/protocol changes
65
- - Zero vendor SDK runtime dependencies
66
- - Provider field is always caller-supplied
67
- - All records use Wire 0.2 `evidence` kind
68
- - Observational only; never enforces, computes, or determines
69
- - Fail-closed validation on malformed input
100
+ [Docs](https://www.peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac) | [Originary](https://www.originary.xyz)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peac/adapter-runtime-governance",
3
- "version": "0.12.9",
3
+ "version": "0.12.10",
4
4
  "description": "Runtime governance adapter for PEAC interaction records with AGT mapper",
5
5
  "main": "dist/index.cjs",
6
6
  "module": "dist/index.mjs",
@@ -39,8 +39,8 @@
39
39
  "node": ">=22.0.0"
40
40
  },
41
41
  "dependencies": {
42
- "@peac/protocol": "0.12.9",
43
- "@peac/crypto": "0.12.9"
42
+ "@peac/crypto": "0.12.10",
43
+ "@peac/protocol": "0.12.10"
44
44
  },
45
45
  "devDependencies": {
46
46
  "@types/node": "^22.0.0",
@@ -51,13 +51,15 @@
51
51
  "keywords": [
52
52
  "peac",
53
53
  "peacprotocol",
54
+ "originary",
54
55
  "interaction-records",
55
56
  "signed-records",
56
57
  "runtime-governance",
57
58
  "agent-records",
58
59
  "agent-governance",
59
60
  "mcp",
60
- "a2a"
61
+ "a2a",
62
+ "adapter"
61
63
  ],
62
64
  "scripts": {
63
65
  "prebuild": "rm -rf dist",