413 lines
11 KiB
Markdown
413 lines
11 KiB
Markdown
# Reporting Governance Capability Descriptor
|
|
|
|
## Purpose
|
|
|
|
This document defines the **capability descriptor** for the reporting-governance plugin.
|
|
|
|
It turns runtime support from implied prose into a machine-readable contract that can be:
|
|
|
|
- validated before deployment
|
|
- checked against deployment profiles
|
|
- attached to audit bundles
|
|
- used by the next implementation stage for evaluator / decision-runner wiring
|
|
|
|
This spec is intentionally the next step after:
|
|
|
|
- `docs/specs/reporting-governance-adapter-interface.md`
|
|
- `docs/specs/reporting-governance-deployment-model.md`
|
|
- `schemas/reporting-governance/adapter-capabilities.schema.json`
|
|
|
|
The adapter-interface spec defines **what adapters must be able to describe**.
|
|
This capability-descriptor spec defines **how one concrete runtime publishes that description as a package artifact**.
|
|
|
|
## Why this exists now
|
|
|
|
The current mainline already has:
|
|
|
|
- canonical event / evidence / decision / policy-pack contracts
|
|
- deployment profiles
|
|
- a validated watchdog reference runtime composition
|
|
|
|
But the plugin still lacks one package-level truth source answering:
|
|
|
|
- which runtime surfaces exist in this deployment
|
|
- which enforcement actions are actually available
|
|
- whether the runtime can only queue, can bridge, or can truly ack final delivery
|
|
- which storage and receipt guarantees are real
|
|
|
|
Without a capability descriptor, the next evaluator / decision-runner stage would still have to guess runtime powers from docs and scripts.
|
|
|
|
## Scope
|
|
|
|
This spec defines:
|
|
|
|
1. the package role of a capability descriptor
|
|
2. the minimum descriptor shape
|
|
3. the OpenClaw reference descriptor for the watchdog composition
|
|
4. package-boundary implications for `core/`, `adapters/`, `storage/`, `artifacts/`, and reference implementations
|
|
5. how evaluator / decision-runner should consume descriptor data next
|
|
|
|
This spec does **not** define:
|
|
|
|
- the policy evaluator itself
|
|
- the deployment-profile schema
|
|
- one mandatory programming language API
|
|
- the full audit export manifest format
|
|
|
|
## Mainline decision
|
|
|
|
The reporting-governance plugin now uses this package distinction:
|
|
|
|
- **schema**: validation contract for descriptor shape
|
|
- **capability descriptor**: one concrete runtime claim validated by that schema
|
|
- **deployment profile**: requested operating posture
|
|
- **adapter modules**: implementation surfaces that may satisfy some or all requested posture
|
|
|
|
In short:
|
|
|
|
- profiles express **desired behavior**
|
|
- capability descriptors express **actual runtime power**
|
|
- evaluator / decision-runner must operate from the intersection of both
|
|
|
|
## Package location
|
|
|
|
Capability descriptors belong under the plugin package boundary:
|
|
|
|
```text
|
|
plugins/reporting-governance/
|
|
capabilities/
|
|
openclaw-watchdog-reference.json
|
|
examples/
|
|
openclaw-watchdog-reference.descriptor.example.json
|
|
```
|
|
|
|
The canonical validation schema remains under:
|
|
|
|
```text
|
|
schemas/reporting-governance/capability-descriptor.schema.json
|
|
```
|
|
|
|
This keeps the split clear:
|
|
|
|
- `schemas/` = canonical validation contracts
|
|
- `plugins/reporting-governance/capabilities/` = package-owned runtime declarations; `runtime.entrypoint: "scripts/..."` is resolved relative to the package root
|
|
- `plugins/reporting-governance/examples/` = copyable reference inputs using the same package-root-relative `scripts/...` semantics
|
|
|
|
## Descriptor responsibilities
|
|
|
|
A capability descriptor must answer five questions.
|
|
|
|
### 1. What runtime is this?
|
|
|
|
Examples:
|
|
|
|
- `openclaw`
|
|
- future host runtimes
|
|
- future embedded or CI-only runtimes
|
|
|
|
### 2. Which adapter surfaces are present?
|
|
|
|
Examples:
|
|
|
|
- `watchdog`
|
|
- `queue`
|
|
- `dispatcher`
|
|
- `bridge`
|
|
- `sender_binding`
|
|
- `orchestrator`
|
|
|
|
### 3. Which governance actions are truly available?
|
|
|
|
Examples:
|
|
|
|
- block transition
|
|
- rewrite message
|
|
- annotate placeholder
|
|
- force checkpoint
|
|
- request review
|
|
- downgrade status
|
|
- escalate
|
|
|
|
### 4. What notification truth model is supported?
|
|
|
|
At minimum, whether the runtime distinguishes:
|
|
|
|
- `prepared`
|
|
- `queued`
|
|
- `dispatched`
|
|
- `pending_external_send`
|
|
- `acked`
|
|
- `blocked`
|
|
|
|
### 5. What persistence and audit guarantees exist?
|
|
|
|
Examples:
|
|
|
|
- can events be persisted?
|
|
- can receipts be written?
|
|
- can original attempted messages be preserved?
|
|
- can decision outputs be stored yet, or is that still pending the next phase?
|
|
|
|
## Descriptor shape
|
|
|
|
The canonical descriptor shape is validated by:
|
|
|
|
- `schemas/reporting-governance/capability-descriptor.schema.json`
|
|
|
|
The schema reuses the same top-level resource model already established for adapter capabilities:
|
|
|
|
- `apiVersion`
|
|
- `kind`
|
|
- `metadata`
|
|
- `runtime`
|
|
- `compatibility`
|
|
- `capabilities`
|
|
- optional `defaults`
|
|
- optional `notes`
|
|
|
|
## OpenClaw reference descriptor
|
|
|
|
The first package-mainline descriptor is the **OpenClaw watchdog reference composition**.
|
|
|
|
Descriptor identity:
|
|
|
|
- runtime: `openclaw`
|
|
- mode: `hybrid`
|
|
- runtime `entrypoint`: `scripts/watchdog_auto_notify_orchestrator.mjs` resolved from `plugins/reporting-governance/` package root
|
|
- surfaces:
|
|
- `watchdog`
|
|
- `queue`
|
|
- `dispatcher`
|
|
- `bridge`
|
|
- `sender_binding`
|
|
- `orchestrator`
|
|
- `scheduler`
|
|
- `storage`
|
|
|
|
### What it must claim
|
|
|
|
This reference descriptor should claim support for:
|
|
|
|
- watchdog overdue observation
|
|
- canonical watchdog event generation
|
|
- queue-backed operator notices
|
|
- spool/handoff dispatch
|
|
- bridge-supervised sender invocation
|
|
- truthful `acked | blocked | pending_external_send` outcomes
|
|
- persistence of events, evidence, queue items, spool artifacts, and receipts
|
|
|
|
### What it should not overclaim
|
|
|
|
At this stage, the reference descriptor should **not** overclaim:
|
|
|
|
- full inline hook interception as complete
|
|
- final delivery proof in every deployment
|
|
- fully packaged decision persistence if the evaluator / decision runner is not extracted yet
|
|
- all completion-claim governance paths
|
|
|
|
This is why some support levels remain `partial` rather than `full`.
|
|
|
|
## Package boundary decisions
|
|
|
|
This spec fixes the package skeleton boundaries needed for the next implementation round.
|
|
|
|
## `src/core/`
|
|
|
|
`core/` contains runtime-agnostic governance logic.
|
|
|
|
It should own:
|
|
|
|
- canonical event normalization
|
|
- evidence building / evidence-reference shaping
|
|
- policy evaluation
|
|
- decision execution planning
|
|
- capability/profile compatibility checks
|
|
|
|
It should **not** own:
|
|
|
|
- cron installation
|
|
- filesystem-specific queue scanning loops
|
|
- OpenClaw sender invocations
|
|
- repo-local wrapper scripts
|
|
|
|
Minimum package direction:
|
|
|
|
```text
|
|
src/core/
|
|
capability-profile-compatibility.mjs
|
|
decision-runner.mjs
|
|
evidence-builder.mjs
|
|
event-normalizer.mjs
|
|
policy-evaluator.mjs
|
|
```
|
|
|
|
## `src/adapters/`
|
|
|
|
`adapters/` contains runtime-facing integration modules.
|
|
|
|
It should own:
|
|
|
|
- OpenClaw watchdog adapter wrapper
|
|
- queue / dispatcher adapter wrapper
|
|
- bridge adapter wrapper
|
|
- sender-binding adapter wrapper
|
|
- orchestrator adapter wrapper
|
|
|
|
It may initially wrap existing repo scripts while package extraction is still in progress.
|
|
|
|
It should **not** absorb canonical policy semantics that belong in `core/`.
|
|
|
|
Minimum package direction:
|
|
|
|
```text
|
|
src/adapters/
|
|
bridge-adapter.mjs
|
|
dispatcher-adapter.mjs
|
|
orchestrator-adapter.mjs
|
|
sender-binding-adapter.mjs
|
|
watchdog-adapter.mjs
|
|
```
|
|
|
|
## `src/storage/`
|
|
|
|
`storage/` contains package-level readers/writers for durable governance artifacts.
|
|
|
|
It should own contracts for:
|
|
|
|
- event store
|
|
- evidence store
|
|
- receipt store
|
|
- queue-item store
|
|
- spool-artifact store
|
|
- future decision store
|
|
- future audit export manifest support
|
|
|
|
It should not define governance meaning; it only persists governed artifacts.
|
|
|
|
Minimum package direction:
|
|
|
|
```text
|
|
src/storage/
|
|
decision-store.mjs
|
|
event-store.mjs
|
|
evidence-store.mjs
|
|
queue-store.mjs
|
|
receipt-store.mjs
|
|
spool-store.mjs
|
|
```
|
|
|
|
## `artifacts/` boundary
|
|
|
|
The plugin package does not need a required checked-in `artifacts/` source directory yet.
|
|
Instead, **artifacts** are the runtime outputs produced by storage contracts and runtime bindings.
|
|
|
|
For current OpenClaw reference behavior, the artifact classes are still represented by runtime directories such as:
|
|
|
|
- `state/long-task-watchdog/`
|
|
- `state/long-task-watchdog-events/`
|
|
- `state/operator-notify-queue/`
|
|
- `state/operator-notify-dispatch-spool/`
|
|
- `state/operator-notify-bridge-receipts/`
|
|
- `state/operator-notify-sender-attempts/`
|
|
|
|
Mainline interpretation:
|
|
|
|
- these are **runtime artifact locations**
|
|
- package `src/storage/` should become the code boundary that reads/writes them
|
|
- future audit export bundles should consume these classes through storage abstractions rather than raw script coupling
|
|
|
|
## Reference implementations boundary
|
|
|
|
Reference implementations are executable, runtime-specific realizations of the package contracts.
|
|
|
|
For this MVP stage, the main reference implementation is the watchdog chain described in:
|
|
|
|
- `CODER_WATCHDOG_REPORT.md`
|
|
|
|
Within the package skeleton, it belongs under:
|
|
|
|
```text
|
|
plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md
|
|
```
|
|
|
|
and is represented in code-adjacent terms by:
|
|
|
|
- `src/adapters/watchdog-adapter.mjs`
|
|
- `src/adapters/dispatcher-adapter.mjs`
|
|
- `src/adapters/bridge-adapter.mjs`
|
|
- `src/adapters/sender-binding-adapter.mjs`
|
|
- `src/adapters/orchestrator-adapter.mjs`
|
|
|
|
This means the **watchdog reference runtime composition is categorized as a reference implementation, not as plugin core**.
|
|
|
|
That is the key boundary that keeps the next evaluator / decision-runner work clean.
|
|
|
|
## Consumption by evaluator / decision runner
|
|
|
|
The next implementation stage should use the capability descriptor in two places.
|
|
|
|
### 1. Preflight compatibility
|
|
|
|
Before executing a policy action, the runtime should compare:
|
|
|
|
- requested profile behavior
|
|
- policy-required action
|
|
- actual adapter capability support
|
|
|
|
Examples:
|
|
|
|
- if `force_checkpoint` is requested but only queue/bridge notice is available, downgrade to honest deferred notice + receipt
|
|
- if direct send is requested but only `pending_external_send` is supportable, preserve the weaker truthful state
|
|
|
|
### 2. Action planning
|
|
|
|
The decision runner should use capability support to choose execution paths such as:
|
|
|
|
- inline block
|
|
- queue-only notice
|
|
- bridge-mediated send
|
|
- status downgrade + review request
|
|
- blocked-with-gap receipt
|
|
|
|
This keeps the evaluator portable and avoids encoding OpenClaw-specific assumptions inside `core/`.
|
|
|
|
## Verification expectations
|
|
|
|
Capability descriptor work should be verified at minimum by:
|
|
|
|
1. schema validation of the descriptor JSON
|
|
2. package skeleton presence checks
|
|
3. consistency review against:
|
|
- adapter-interface spec
|
|
- deployment model
|
|
- roadmap lane terminology
|
|
|
|
## Minimal synchronization with roadmap and deployment model
|
|
|
|
This capability-descriptor step advances:
|
|
|
|
- roadmap lane 3: package extraction
|
|
- roadmap lane 4: capability/profile/deployment binding
|
|
|
|
The deployment model does not need redesign.
|
|
It only needs to recognize that the first concrete package artifact for this lane is now:
|
|
|
|
- a package-owned OpenClaw capability descriptor
|
|
- plus the minimal package skeleton that gives it a stable home
|
|
|
|
## Summary
|
|
|
|
This spec establishes the reporting-governance capability descriptor as the package-level truth contract between:
|
|
|
|
- runtime-specific adapter power
|
|
- deployment-profile intent
|
|
- future evaluator / decision-runner behavior
|
|
|
|
It also fixes the package boundaries needed for the next phase:
|
|
|
|
- `core/` = runtime-agnostic governance logic
|
|
- `adapters/` = runtime integration surfaces
|
|
- `storage/` = durable artifact I/O contracts
|
|
- runtime `artifacts/` = produced outputs, not core source
|
|
- watchdog chain = reference implementation housed under the package skeleton, not plugin core
|