RExecOp

Regulated Execution Operations control-plane for profile-defined workflows, bound to GovEngine governance and SCLite auditable truth.

RExecOp (package name: rexecop) is the deterministic runner, orchestrator, and executor for domain profiles. It plans and runs declared workflow steps, enforces operational lifecycle mechanics, and projects completed work into SCLite-compatible artifacts — without becoming a policy engine or a parallel truth layer.

Status

Project sentence

RExecOp runs profile-defined operations under GovEngine admission and records auditable outcomes through SCLite — profiles own meaning, GovEngine owns governance, SCLite owns proof, RExecOp owns execution mechanics.

Stack position

One operation crosses all layers. GovEngine owns policy and admission decisions; RExecOp enforces admitted neutral controls and executes the workflow; SCLite validates the proof bundle emitted after execution.

Profiles (tecrax, fixtures)
  intents, workflows, connector contracts, validation rules
        |
        v
RExecOp  plan -> GovEngine policy/admission -> lifecycle FSM
        |                  allowed | blocked | approval_required
        v
RExecOp  admitted controls -> step execution -> profile validation
        v
RExecOp  project runtime facts + GovEngine admission into SCLite artifact shapes
        |
        v
SCLite   validate schemas, ticket binding, review_bundle (truth authority)

For a configured signed-decision authority, each connector attempt receives an immutable runtime permit before I/O. After I/O, RExecOp emits a bounded receipt binding and requires GovEngine conformance for the same decision, permit, attempt, lease/fencing and inventory plus output postconditions. Only digest projections enter the existing SCLite receipt; SCLite remains truth authority.

RExecOp also owns the orchestration-specific observation, finding, reaction, trigger, watchdog and automation contract resources. They are exposed through the immutable rexecop.contracts.orchestration resolver under rexecop.io/*@v0.1. SCLite verifies their bytes and descriptors without discovering plugins or interpreting runtime semantics.

Tecrax ships as the tecrax package (rexecop.profiles:tecrax). Ravenclaw is legacy and out of scope for RExecOp.

What RExecOp includes now

Core execution

• Deterministic operation state machine and OperationPlan runtime artifact
• GovEngine port: real GovEngineClient + bootstrap-only StaticGovEngineAdapter
• SCLite port: GovEngine-integration bundle emission (scoped ticket, kernel guard, review pass)
• Profile resolution by path or rexecop.profiles entry point (tecrax)
• Declarative profile validation rules (YAML, not hardcoded domain logic in core)
• Deterministic reaction interpreter (reaction-plan, reaction-start, reaction-replay, reaction explain)
• Reaction automation-chain projection for admitted child-operation planning (automation_chain.v0.1) with GovEngine automation-transition admission refs
• Connectors: mock, http_api, local_shell_readonly, ssh_readonly (bounded output + digests)
• Execution contracts: digest-bound ExecutionRequest / ExecutionReceipt (schema v0.2)
• GovEngine PolicyEngine when environment.policy_pack is set, plus rexecop.policy_pack_lifecycle.v0.1 projections for pack status, digest and enforcement binding
• Operator target catalog and profile-derived operation catalog with drift rejection at start
• Storage: stable-certified single-host FileStore (default); SqliteStore remains alpha-only (REXECOP_STORAGE / --storage)
• Secrets port: REXECOP_SECRET_* and REXECOP_SECRETS_FILE (no plaintext secrets in git or .rexecop/)

Runtime readiness and operator UX

• Runtime root: --root / REXECOP_ROOT, --instance / REXECOP_INSTANCE, init, doctor
• Stable runtime qualification: doctor reports storage/executor/mutation/plugin checks and a machine-readable security_blockers subset for configuration-level security failures
• Input validation: env lint, profile lint, secrets doctor, secrets suggest-ref
• Profile developer surface: profiles list/show, connectors list/show, capabilities list, profile manifest, profile harness, operator metadata projection
• CLI contract registry: contracts cli emits command schemas, formats, exit-code policy and redaction/authority claims for operator-facing surfaces, including command groups, format_matrix and exit_code_matrix
• Candidate 1.x public API: rexecop.public_api.v1 lists the exact supported Python imports, stable CLI registry commands and explicit alpha CLI remainder
• Release evidence v2 binds public wheel/sdist identity, CycloneDX SBOM and GitHub provenance-attestation subjects before durable persistence as versioned GitHub Release assets
• CLI error envelope: registry commands emit rexecop.cli_error.v0.1 on exit code 1 with normalized class, reason code, redacted message and safe next actions
• Observability: bounded structured logs with correlation IDs and artifact refs; observability diagnostics uses the same failure classes as explain-error
• M5 action metadata (no backend IO): action list, action show, action preview, action policy-preview, action validate, action diff --env, action configure --dry-run, action templates list (scope 1.0: http.simple-get, shell/SSH allowlist skeletons)
• Pre-run inspection: policy explain, operations explain, operation explain, operation review, operation diff, runbook show, operations unavailable
• Audit inspection: receipt show, evidence show, chain summary, chain explain, support bundle --redacted for redacted, digest-bound runtime/SCLite projections
• Runtime triage: runtime status, runtime reconstruct-status, ops, explain-error, dead-letter list/show, locks list, runtime recover, backup create/restore, watchdog manual-record
• Lifecycle controls: plan, approve, start, pause/resume, cancel, retry, rollback, validate, escalate, status, history
• Host-owned scheduling: queue, worker run, trigger (see operator scheduler pattern)
• Certified runtime: one fenced executor per FileStore root, operation CAS, atomic FIFO queue claims, durable connector attempts and outcome_indeterminate recovery
• Stable mutation posture: REXECOP_MUTATION_POSTURE defaults to stable_read_only and is rechecked before operation execution and connector I/O; doctor blocks the explicit lab_only mechanics posture
• Execution-kernel stabilization: store-backed runtime ports, a preallocated attempt, atomic GovEngine decision claim, attempt-bound pre-IO runtime permit, stable reason codes, trusted-plugin inventory/allowlist and cycle-safe public imports
• Advisory escalation proposal handling: validate escalation_proposal.v0.1, review without printing raw explanation text, and record accept_for_planning/reject decisions without planning, approval or execution

Examples and fixtures

• Domain-neutral examples/first-run-demo/ and examples/profiles/runtime-fixture/ for onboarding, lifecycle, policy and connector regressions
• Tecrax product semantics live only in the external tecrax package

What RExecOp does not include

• A policy engine (GovEngine is the governance authority)
• SCLite schema authority or long-term truth storage
• Domain profiles in core (no Tecrax/Ravenclaw operational logic in src/rexecop)
• Production cron/recurrence scheduler (host-owned worker + systemd/cron pattern only)
• Web UI or multi-tenant RBAC
• Unattended apply on critical infrastructure without operator and governance gates
• mutation_ready or stable live mutation; apply / recovery can be exercised only under the explicit REXECOP_MUTATION_POSTURE=lab_only development posture
• An LLM provider adapter or prompt execution pipeline; current proposal handling is advisory, local and non-executable
• Automatic conversion of accepted advisory proposals into operations; operators must create a normal plan that passes profile validation and GovEngine admission
• Profile-owned graph runbook traversal beyond the current single-step reaction/automation-chain path

Installation

Release candidate package:

python -m pip install "rexecop==1.0.0rc1"
rexecop version

The 1.0.0rc1 wheel is the first stable read-only 1.x candidate. It freezes the documented public API subset, requires a new runtime root instead of migrating alpha state, and retains explicit non-claims for mutation readiness, distributed execution and production-wide security guarantees.

See docs/distribution.md for core wheels, Git installs, private indexes, and the separate Tecrax consumer path.

From source (development):

git clone https://github.com/rozmiarD/RExecOP.git
cd RExecOP
python -m venv .venv && source .venv/bin/activate
git clone https://github.com/rozmiarD/GovEngine.git ../govengine
pip install -e ../govengine
pip install -e ".[dev]"

With the Tecrax profile package:

git clone https://github.com/rozmiarD/tecrax.git ../tecrax
pip install -e ../tecrax

RExecOp 1.x does not ship a tecrax extra. Tecrax is a separate external consumer/plugin with its own release line. CI checks out its source for cross-repository compatibility tests without making it a core install dependency.

Quick start

rexecop version

rexecop --root /tmp/rexecop-first-run init --guided

rexecop --root /tmp/rexecop-first-run doctor \
  --profile examples/first-run-demo/profile/profile.yaml \
  --env examples/first-run-demo/environment.yaml \
  --catalog examples/first-run-demo/catalog.yaml

rexecop operations explain inspect \
  --profile examples/first-run-demo/profile/profile.yaml

rexecop --root /tmp/rexecop-first-run plan \
  --catalog examples/first-run-demo/catalog.yaml \
  --intent inspect \
  --target fixture-target \
  --mode dry_run

See docs/first-run.md for the full no-I/O first-run path with lint checks.

• With tecrax installed, --profile tecrax resolves via entry point.
• For offline tests without a domain package, use examples/profiles/runtime-fixture/profile.yaml.
• Staging http_api template: examples/environments/runtime-fixture.staging.example.yaml

Runtime artifacts live under the selected runtime root: operations, evidence, SCLite bundles, receipt exports, queue, locks and trigger inbox.

CLI overview

The CLI has grown across M1–M5 milestones. Full command reference: docs/cli-reference.md.

Global options: --root, --instance, --storage file|sqlite.

Public interfaces

The 1.x compatibility promise is deliberately smaller than the installed package. rexecop.public_api.public_api_manifest() is the machine-readable source of truth for supported Python imports and CLI stability. Stable CLI surfaces are present in CLI_CONTRACTS; every remaining command is explicitly classified as alpha. Alpha runtime roots require a new root for 1.0 rather than an in-place state migration. See docs/public-api.md.

Development

pip install -e /path/to/tecrax -e ".[dev]"
python scripts/validate_public_truth.py
python scripts/validate_first_run_smoke.py
python scripts/validate_operator_journeys.py
ruff check .
mypy src/rexecop
python -m build && python -m twine check dist/*
pytest
pytest -m delivery   # canonical sign-off scope from tests/delivery_scope.py

GitHub Actions runs on every push and pull request: install tecrax, public truth validation, stack contract validation, profile conformance, first-run smoke, operator journey smoke, ruff, mypy, core boundary grep, secret scan, pytest, and a package-dry-run job (build + twine check).

Documentation

Related repositories

License

MIT — see LICENSE.