183 lines
6.3 KiB
Markdown
183 lines
6.3 KiB
Markdown
# Reporting Governance Plugin
|
|
|
|
This package is the emerging package boundary for the reporting-governance mainline.
|
|
|
|
Current purpose:
|
|
|
|
- give the plugin a real package home
|
|
- publish capability descriptors as package artifacts
|
|
- fix boundaries between `core/`, `adapters/`, `storage/`, and reference implementations
|
|
- prepare the next implementation round for evaluator / decision-runner extraction
|
|
- provide a minimal package-level policy evaluator and decision runner skeleton that can be verified in isolation
|
|
|
|
## Package skeleton
|
|
|
|
```text
|
|
plugins/reporting-governance/
|
|
package.json
|
|
README.md
|
|
capabilities/
|
|
docs/
|
|
examples/
|
|
src/
|
|
core/
|
|
index.mjs
|
|
policy-evaluator.mjs
|
|
decision-runner.mjs
|
|
execute-governance-contract.mjs
|
|
adapters/
|
|
storage/
|
|
reference/
|
|
index.mjs
|
|
test/
|
|
```
|
|
|
|
## Boundary rules
|
|
|
|
### `src/core/`
|
|
Runtime-agnostic governance logic:
|
|
|
|
- canonical event normalization
|
|
- evidence building
|
|
- policy evaluation
|
|
- decision running
|
|
- capability/profile compatibility
|
|
|
|
### `src/adapters/`
|
|
Runtime-facing adapter modules:
|
|
|
|
- watchdog adapter
|
|
- dispatcher adapter
|
|
- bridge adapter
|
|
- sender-binding adapter
|
|
- orchestrator adapter
|
|
|
|
These may initially wrap existing repo scripts while extraction is still in progress.
|
|
|
|
### `src/storage/`
|
|
Durable I/O contracts for governance artifacts:
|
|
|
|
- events
|
|
- evidence
|
|
- queue items
|
|
- spool artifacts
|
|
- receipts
|
|
- future decisions / audit manifests
|
|
|
|
### `src/reference/`
|
|
Reference runtime compositions and migration notes.
|
|
|
|
**The watchdog reference runtime composition belongs here**, as a reference implementation for OpenClaw rather than as package core logic.
|
|
|
|
## Public surface and compatibility
|
|
|
|
Current **public package surface** is intentionally narrow:
|
|
|
|
- root export: `@openclaw/plugin-reporting-governance`
|
|
- adapter exports:
|
|
- `@openclaw/plugin-reporting-governance/adapters`
|
|
- `@openclaw/plugin-reporting-governance/adapters/watchdog`
|
|
- `@openclaw/plugin-reporting-governance/adapters/dispatcher`
|
|
- `@openclaw/plugin-reporting-governance/adapters/bridge-supervisor`
|
|
- `@openclaw/plugin-reporting-governance/adapters/sender-binding`
|
|
- `@openclaw/plugin-reporting-governance/adapters/orchestrator`
|
|
|
|
What is currently exposed from the root export:
|
|
|
|
- `evaluatePolicyPack(...)`
|
|
- `evaluatePolicies(...)`
|
|
- `planDecisionExecution(...)`
|
|
- `executeGovernanceContract(...)`
|
|
- package metadata helpers such as `packageName`
|
|
- package-owned adapter entrypoints and `runWatchdogChain(...)`
|
|
|
|
Compatibility posture for this slice:
|
|
|
|
- `0.1.0-mainline` should be treated as **pre-1.0, surface-tightening phase**.
|
|
- Deep imports into `src/` are **not supported API** even if files exist in-repo.
|
|
- Tests now explicitly enforce that private paths like `src/adapters/runtime-binding.mjs` stay outside `exports`.
|
|
- Adding a symbol to a file under `src/` does **not** mean it is public unless wired through package `exports`.
|
|
- Future tightening of root/adapters exports may still be a breaking change until a stable `1.0` surface is declared.
|
|
|
|
Practical migration rule:
|
|
|
|
- depend on package root exports or declared adapter subpaths only
|
|
- do not couple runtime integrations to repo-private file paths
|
|
- treat capability descriptors and schemas as package artifacts, but not as guaranteed JS import entrypoints unless exported later
|
|
|
|
## Current reference composition
|
|
|
|
The current reference composition is the OpenClaw watchdog chain:
|
|
|
|
```text
|
|
watchdog -> queue -> dispatcher -> bridge -> sender binding -> acked|blocked|pending_external_send
|
|
```
|
|
|
|
Package-home documentation:
|
|
|
|
- `src/reference/openclaw-watchdog-chain.md`
|
|
- `capabilities/openclaw-watchdog-reference.json`
|
|
|
|
Mainline background specs remain in:
|
|
|
|
- `docs/specs/reporting-governance-capability-descriptor.md`
|
|
- `docs/specs/reporting-governance-adapter-interface.md`
|
|
- `docs/specs/reporting-governance-deployment-model.md`
|
|
|
|
## Minimal evaluator / decision runner now included
|
|
|
|
The current package now includes a small but runnable `core/` implementation:
|
|
|
|
- `src/core/policy-evaluator.mjs`
|
|
- `src/core/decision-runner.mjs`
|
|
- `src/core/execute-governance-contract.mjs`
|
|
- `src/core/index.mjs`
|
|
|
|
Current package-core responsibilities:
|
|
|
|
- normalize evaluator facts from canonical event payload + evidence + local context
|
|
- match policy-pack rules by trigger and structured conditions
|
|
- produce canonical decision-model shaped decision objects
|
|
- choose the highest-precedence decision when multiple rules match
|
|
- convert a canonical decision into an execution plan, enforcement intent, and receipt skeleton
|
|
- truthfully degrade unsupported enforcement paths based on the capability descriptor
|
|
- provide one minimal contract path from `capability descriptor -> policy decision -> execution planning`
|
|
|
|
Still **runtime-adapter responsibility** at this stage:
|
|
|
|
- intercepting real outgoing messages or status transitions inline
|
|
- actually sending operator notices
|
|
- acking final delivery to external channels
|
|
- persisting decisions/receipts into a production decision store
|
|
- installing schedulers / watchdog loops / bridge sender bindings
|
|
|
|
This means `core/` now owns evaluation and planning semantics, while adapters still own actual enforcement side effects.
|
|
|
|
## Minimal end-to-end contract slice now included
|
|
|
|
This slice now has one small but testable contract path:
|
|
|
|
1. capability descriptor advertises real enforcement support
|
|
2. policy evaluator emits a canonical decision from event/evidence/context
|
|
3. decision runner converts that decision into execution planning
|
|
4. the result declares:
|
|
- adapter-dispatch actions required
|
|
- package-core actions possible locally
|
|
- blocked mandatory actions when capability support is missing
|
|
- truthful delivery / receipt state
|
|
|
|
This is intentionally **planning-level end-to-end**, not full live inline interception.
|
|
It proves contract alignment without pretending all runtime enforcement is already extracted.
|
|
|
|
## Not yet included
|
|
|
|
This package still does **not** claim full implementation of:
|
|
|
|
- generalized event normalization modules
|
|
- generalized evidence builder modules
|
|
- production decision persistence
|
|
- complete rewrite / placeholder / review / status-downgrade adapter execution
|
|
- non-watchdog full runtime governance interception
|
|
|
|
It now provides the first package-mainline evaluator / decision-runner core, plus a minimal end-to-end contract proof, but the remaining enforcement surface is still intentionally honest about adapter gaps.
|