WitnessOps Catalog
How the WitnessOps catalog describes available governed execution capabilities.
The WitnessOps catalog is the governed description layer for executable runbooks. It constrains what can be requested, how capability boundaries are declared, and what evidence contracts must exist before execution is allowed.
1. Problem this page solves
Without a formal catalog boundary, capability claims drift into ad hoc execution and undocumented operator expectations. That breaks review because a verifier cannot tell which behavior was declared, which behavior actually executed, and which evidence requirements were in force.
This page defines the catalog as a governance mechanism so capability scope and evidence expectations stay explicit and testable.
2. Reader outcome
After this page, you should be able to:
- explain what the WitnessOps catalog governs and what it does not govern
- identify the minimum contract fields each catalog entry must declare
- separate catalog description from runtime truth and analyst judgment
- apply observed-vs-inferred boundaries when reading catalog-backed execution results
3. Mechanism-first catalog model
Treat the catalog as a versioned control contract, not as a feature brochure.
| Catalog role | What it is | What it is not |
|---|---|---|
| Capability declaration | A bounded, versioned runbook entry that can be authorized for execution | A promise that execution will always succeed |
| Governance anchor | The source of declared scope, authority requirements, and evidence expectations | A substitute for policy gates, approvals, or runtime enforcement |
| Evidence contract pointer | A declaration of what artifacts and receipt linkage must exist when the run executes | Proof that captured artifacts are globally true beyond their capture context |
If a capability is not declared in the catalog, it is outside the governed execution lane.
4. What catalog entries must specify
Each entry must specify the following at minimum:
| Required field | Minimum declaration | Why it matters |
|---|---|---|
| Scope | Allowed target boundary, action boundary, and disallowed operations | Prevents scope creep and ad hoc execution expansion |
| Authority | Required policy state, approval requirements, and identity/role assumptions | Makes authorization preconditions auditable |
| Artifacts and evidence expectations | Expected outputs, capture format, and receipt-linkage requirements | Defines what must be present for downstream review and verification |
| Failure and escalation behavior | Failure classes, stop/continue rules, and escalation path | Ensures failure handling is governed rather than improvised |
Entries that omit any of these fields should be treated as incomplete control contracts, not production-ready capability definitions.
5. Ownership boundary
The catalog describes allowed and expected behavior. It does not replace runtime facts.
| Boundary area | Catalog responsibility | Outside catalog responsibility |
|---|---|---|
| Definition layer | Declares capability contract, version, and required governance metadata | Proves that a specific execution instance met real-world objectives |
| Runtime layer | Provides the reference contract used to evaluate execution conformance | Guarantees environment stability, remote system truth, or tool correctness |
| Operational judgment | Supplies bounded terms for interpreting run outcomes | Decides final risk significance without human review |
Use the catalog to frame review, then use receipts and execution evidence to test what actually happened.
6. Observed vs inferred separation
| Layer | Observed | Inferred |
|---|---|---|
| Catalog record | Declared runbook contract, version, and governance fields | That every future execution will satisfy intent |
| Execution evidence | Captured artifacts, timestamps, receipt references, and status outcomes | That external systems were truthful or complete in all dimensions |
| Operational conclusion | Analyst statement tied to observed evidence and stated assumptions | Broad certainty claims beyond captured scope |
Keep this separation explicit to avoid promoting policy metadata into factual runtime certainty.
7. Trust assumptions and limits
Catalog use depends on bounded assumptions:
- catalog data is maintained under change control and version integrity
- runtime enforcement correctly applies the declared catalog contract
- evidence capture pipelines preserve artifact integrity and linkage
- external systems and environments may still fail, drift, or misreport
- human review is required before elevating execution output into high-confidence operational conclusions
A catalog entry can narrow ambiguity, but it cannot remove uncertainty outside captured evidence and governed controls.
8. Next-page handoff to /docs/evidence/execution-chains
Next, read Execution Chains for how receipt-level events are connected into continuity that can be verified as an ordered proof story.