Declarative intent → deterministic execution contract → agent / harness

Decretum

Decretum turns structured intent into a deterministic execution contract for agents and harnesses.

Decretum is a domain-neutral Declarative Execution Compiler. It combines schemas, recipes, profiles, provider/integration registries, discovery, validation, policy, and deterministic resolution to produce a portable Execution Contract.

Security research is Decretum's reference domain, not its architectural boundary. The same compiler model can describe software engineering, infrastructure automation, data engineering, incident response, scientific experiments, and other reproducible technical work.

Architecture

Decretum is not a runtime. It defines what can be executed and produces a portable execution contract. It does not execute work, manage agent/researcher interaction, collect evidence, maintain findings, or generate reports.

After compilation, Decretum stops. The contract is passed to an external harness or agent runtime.

If execution later needs a new capability or changed requirement, the request returns to Decretum for validation, resolution, and recompilation.

The model

Schema       = what exists / semantic boundaries
Recipe       = what should be done
Profile      = execution characteristics and preferences
Registry     = available implementations
Resolver     = deterministic capability binding
Compiler     = portable contract generation
Harness      = actual execution and interaction
Store        = persistent execution/research memory

The important separation is:

                    DECRETUM
          Declarative Execution Compiler
                       |
       +---------------+---------------+
       |               |               |
    Schema           Recipe          Profile
   "what"           "do"            "how"
       |               |               |
       +---------------+---------------+
                       |
                    Resolver
                       |
     capability + provider + integration
       + harness + readiness + policy
                       |
                       v
               Execution Contract
                       |
                       v
              External Harness/Agent
                       |
          +------------+------------+
          |            |            |
       execute      interact      persist
          |            |            |
          +------------+------------+
                       |
                    Store

Domain packs

The compiler core is domain-neutral. Domain-specific semantics live in registries and schemas rather than compiler branches.

Examples:

• Security research — malware, network, forensics, detection and cloud investigation
• Software engineering — source changes, dependencies, tests, builds and containers
• Infrastructure — VM, container, network and deployment requirements
• Data engineering — datasets, transforms, validation and artifacts
• Scientific/technical experiments — instruments, observations, analysis and evidence

A domain pack contributes capabilities, schemas, recipes, profiles and provider metadata. It does not change the core resolver/compiler semantics.

Why structured contracts instead of broad markdown specifications?

Markdown is excellent for explanation. It is not a deterministic execution interface.

Decretum separates:

human intent
    |
    v
structured schema + recipe + profile
    |
    v
validated resolution
    |
    v
portable execution contract
    |
    v
agent / harness execution

This gives agents a machine-readable boundary while keeping implementation choices outside the recipe.

Example: software engineering

A software task can use the same compiler:

apiVersion: decretum.dev/v1
kind: ExecutionRecipe
domain: software_engineering
id: build-user-service
name: Build User Service
version: "1.0"
objective: Build and validate a Python service.

capabilities:
  - source.read
  - source.modify
  - dependency.install
  - test.execute
  - artifact.build
  - container.build

profiles:
  infrastructure: local-dev
  language: python
  testing: pytest
  container: docker
  agent: coding-agent

completion:
  required:
    - tests_pass
    - artifact_built
    - container_built

The same intent can be compiled against another preference set:

profiles:
  infrastructure: isolated-dev-vm
  testing: pytest
  container: podman
  agent: enterprise-coding-agent

The recipe describes intent. The profile expresses preferences. The provider registry determines what is actually available.

Security research reference example

id: suspicious-network-investigation
name: Suspicious Network Investigation
version: "1.0"
role: threat_researcher
objective: Determine whether the sample creates unexpected network activity.

capabilities:
  - process.observe
  - network.capture
  - artifact.collect

infrastructure_profile: isolated-linux-vm
instrumentation_profile: linux-network-observation
harness_profile: interactive-research

The recipe does not contain Lima/Docker lifecycle, MCP implementation, agent prompts, or runtime-specific code.

End-to-end workflow

1. Define structured intent.
2. Reference canonical capabilities.
3. Select profiles/preferences.
4. Validate the recipe.
5. Discover available execution surfaces.
6. Resolve capability → provider → integration → harness.
7. Check readiness and policy.
8. Compile the Execution Contract.
9. Hand the contract to the external harness.
10. The harness executes, interacts, and persists its state.
11. If requirements change, return to Decretum and compile a new contract.

Decretum does not perform steps 9–10.

Capability evolution

DISCOVER
   |
PROPOSE
   |
SEMANTIC REVIEW
   |
APPROVE
   |
CANONICAL CAPABILITY
   |
PROVIDER IMPLEMENTATIONS

Discovery can propose a capability, but it cannot silently mutate canonical semantics.

Quick start

git clone https://github.com/Opposum0112/Decretum.git
cd Decretum
uv sync
decretum capabilities discover
decretum validate recipes/<recipe>.yaml
decretum resolve recipes/<recipe>.yaml
decretum compile recipes/<recipe>.yaml

Nothing in Decretum's validate/resolve/compile path executes the work.

Resolution chain

Capability
    |
Provider
    |
Integration
    |
Execution surface
    |
Harness compatibility
    |
Host/provider readiness
    |
Policy compatibility
    |
READY / BLOCKED

Architecture boundary

Decretum deliberately does not become:

• an agent runtime
• a workflow engine
• a VM/container runtime
• an evidence database
• a finding engine
• a report generator
• a long-running researcher process
• a Codex/Goose/OpenCode replacement

Instead:

Decretum
  = declarative intent -> deterministic contract

Harness / Agent
  = interactive execution environment

Store
  = persistent execution or research memory