# 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.