RExecOp

RExecOp is a domain-neutral execution kernel and runtime for controlled, auditable operations.

It turns an accepted operation into bounded execution attempts: it coordinates operation state, queues, leases, fencing, retries and recovery, dispatches connectors, and produces evidence describing what was attempted and observed.

RExecOp does not decide what an operation means or whether an organization should allow it. Domain semantics belong to profiles, governance decisions belong to GovEngine, and canonical evidence contracts and verification belong to SCLite. RExecOp owns the runtime mechanics that connect those inputs and decisions to actual I/O.

Release status

Item	Current value
Current source line	1.0.0rc3.dev0
Release qualification	development-only, unqualified, unreviewed, untagged and unpublished
Previous public line	1.0.0rc1 (PyPI)
Maturity	Development line inheriting the stable read-only core; no rc3 qualification claim
Python	3.11 or newer
Public 1.0.0rc1 wheel dependencies	govengine==1.0.0rc1, sclite-core==2.0.0
Current main dependencies	govengine==1.0.0rc2, sclite-core==2.0.1
Default posture	stable_read_only
Mutating execution	Blocked by the stock stable posture
Compatibility	Stack contract compatibility

The current 1.0.0rc3.dev0 source is not qualified by any rc3 operational or security-review record. The immutable rc2 source-preparation commit 0c793936b940cf0e2235a916df7a485f69b589e8 is qualified by the public-safe rexecop.operational_qualification.v3 record. It covers an exact-stack non-editable install, bounded live read-only validation, deterministic local-fixture recovery and disclosure review; it does not claim release-artifact identity, mutation readiness or independent security review and does not qualify the current development source. The prior functional source is operationally qualified at 8a8609150388866a21afddca5bf773cd6ec120cd and remains historical evidence in 1.0.0rc2-operational.json. Neither historical rc2 record may be reused as rc3 evidence. This development line has no release tag, release artifacts or public-index publication. The previous 1.0.0rc1 wheel remains immutable and retains the dependency metadata with which it was published.

Why RExecOp exists

Calling a connector is easy. Safely coordinating an operation around that call is harder.

Before and after I/O, a runtime may need to claim work atomically, bind it to the current executor, persist an attempt, enforce governance controls, recover after a crash, and produce evidence without intentionally persisting secret material or unbounded output. RExecOp provides those runtime mechanics without embedding the semantics of a particular business or infrastructure domain. Connector before/after state is bounded while transient and recursively redacted before durable operation persistence. Existing runtime roots are not rewritten by later binaries and must still be treated as sensitive.

Where it fits

Domain profile
  intent, targets, workflow and validation semantics
        |
        v
RExecOp planning
  validate inputs and build the operation plan
        |
        v
GovEngine decision where required
  policy, governance, admission and execution authorization
        |
        v
RExecOp execution
  lifecycle, queue/lease/fencing, connector I/O and recovery
        |
        v
SCLite verification
  canonical evidence contracts, integrity and verification

These are ownership boundaries, not a claim that every compatibility path uses every component identically. Mutating operations require GovEngine governance. Read-only operations can evaluate configured policy, but the explicit legacy_read_only compatibility path does not carry a signed per-attempt GovEngine decision and must not be presented as governance authenticity.

RExecOp owns the orchestration-specific observation, finding, reaction plan, escalation proposal, trigger decision, watchdog decision and automation-chain contracts. SCLite provides the canonicalization and verification machinery used for their evidence projections; it does not own their runtime semantics.

Tecrax is a separate domain-profile package and downstream consumer. It is not part of the RExecOp distribution or release train. Ravenclaw is legacy and out of scope.

See Architecture for the complete ownership model.

What RExecOp claims

Within its documented contracts and supported configuration, RExecOp provides:

• deterministic orchestration decisions for equivalent recorded inputs and state;
• durable operation and attempt records around connector execution;
• atomic queue claims, leases and fencing against stale executors;
• bounded retry, rollback and recovery transitions;
• explicit outcome_indeterminate handling for the post-I/O, pre-durable-result uncertainty window;
• pre-I/O governance enforcement for mutating execution;
• connector dispatch through declared runtime capabilities;
• bounded, redacted audit projections for supported execution paths;
• versioned stable and alpha public-interface classifications;
• exact compatibility pins for the supported GovEngine and SCLite line.

External I/O itself is not deterministic. The deterministic claim applies to RExecOp decisions over equivalent recorded inputs and state.

What RExecOp does not claim

RExecOp does not claim that:

• arbitrary operations, profiles, plugins or connectors are safe;
• external side effects are exactly-once;
• a successful connector call proves the intended real-world outcome;
• recovery can always determine whether an interrupted side effect occurred;
• read-only compatibility mode carries signed governance authenticity;
• the stock 1.0.0rc2 CLI supports unrestricted production mutation;
• redaction makes every runtime artifact safe to publish without operator review;
• RExecOp is a policy engine, secret manager, domain workflow product, long-running scheduler service or truth database;
• RExecOp replaces GovEngine or SCLite;
• installing the package supplies trustworthy signer, verifier, approval, storage or connector adapters for a particular production environment.

The current security posture and residual risks are documented in Safety model, Known limitations, and Security threat model.

Current 1.0.0rc3.dev0 source surface

This inventory combines behavior inherited from rc2 with post-audit changes that exist only on the current rc3.dev0 source line; those changes are not part of rc2. It is not a claim that an rc3 candidate ships or has passed qualification or review.

Operation runtime

• operation planning and lifecycle state;
• atomic FIFO queue claims and one fenced executor per FileStore root;
• durable connector attempts, retry, rollback and recovery;
• host-driven worker, trigger, reaction and watchdog mechanics.

Execution safety

• stable_read_only as the default mutation posture;
• pre-I/O mutation posture and permit checks;
• attempt, lease, fencing, runtime-instance and capability-inventory bindings;
• Post-audit rc3.dev0 source change: exact profile/runtime-bound shared_state.execution_context validation before production connector I/O; missing, duck-typed, malformed or mismatched context fails closed before dispatch. The exact StaticFixtureRuntime type is the deterministic no-I/O fixture exception only;
• Post-audit rc3.dev0 source change: production GovEngine composition rejects caller-supplied preview.admission_compose and split compose-authority fields. Complete synthetic compose input is accepted only by the explicitly named NonProductionFixtureGovEngineAdapter test fixture;
• bounded connector output, receipt bindings and explicit uncertainty states.

Connectors and profiles

• profile resolution by path or rexecop.profiles entry point;
• declarative workflow, environment, target and capability validation;
• mock, http_api, local_shell_readonly and ssh_readonly connector implementations;
• HTTP actions treat methods other than GET, HEAD and OPTIONS as mutating by default; only a matched, validated profile action may provide a typed mutating: false read-RPC override. The effective mutation fact is preserved in typed execution and action previews, and possible post-I/O mutating failures are reported as non-retryable outcome_indeterminate.
• separate external domain packages such as Tecrax.

Evidence and operator inspection

• SCLite-compatible operation bundles and receipt projections;
• operation review, operation diff, receipt show, evidence show, chain summary, chain explain, reaction explain and support bundle --redacted;
• structured logs, observability diagnostics, runtime status, explain-error, dead-letter list, locks list and runbook show;
• stable rexecop.cli_error.v0.1 error envelopes.

Interface contracts

• the rexecop.public_api.v1 Python-import manifest;
• a machine-readable CLI registry from contracts cli;
• format_matrix, exit_code_matrix and stable/alpha command classifications;
• profile developer commands including secrets doctor, secrets suggest-ref, profiles list, profile manifest, profile harness, connectors list, capabilities list, action list, action show, action preview, action configure, action diff, action templates, action policy-preview, action validate, operations unavailable, runtime recover, backup create and watchdog manual-record.

The built-in read-only action templates include http.simple-get and bounded shell/SSH allowlist skeletons. Templates describe configuration shapes; they do not execute backend I/O.

The HTTP connector also percent-encodes resolved placeholder values within their declared URL component and bounds upstream error-body reads to 4096 bytes before diagnostic parsing. See the connector contract for the complete retry, response-bound and destination-safety rules.

The exhaustive command and schema inventories live in CLI reference and Public API, not in this overview.

Install

The current public package remains the previous immutable line:

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

For a source checkout used for development:

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

That checkout reports 1.0.0rc3.dev0 and is for development only; it must not be represented as an rc3 release or public-index artifact.

See Distribution for wheel, source, private-index and release-verification guidance.

Read-only quick start

The bundled first-run fixture plans a no-I/O operation. Materialize it into a new local directory first; the command refuses existing directories and never creates a runtime root or executes a workflow:

rexecop version

rexecop examples materialize --output /tmp/rexecop-first-run-demo

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

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

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

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

Continue with First run. Runtime state belongs under the selected --root; treat that directory as sensitive even when using redacted inspection commands.

No mutating quick start is provided. The stock stable posture intentionally blocks mutating execution.

Execution model

accept -> plan -> govern when required -> claim and validate permit
       -> persist attempt -> revalidate pre-I/O controls -> perform I/O
       -> persist outcome
       -> project evidence -> terminal state or recovery

A connector may complete externally before its result becomes durable. RExecOp records that uncertainty as outcome_indeterminate; it does not invent an exactly-once guarantee.

Public interfaces

rexecop.public_api.public_api_manifest() is the machine-readable source of truth for supported Python imports and CLI stability. The 1.x compatibility promise is deliberately smaller than the installed package:

• stable commands and imports carry the documented 1.x compatibility policy;
• alpha commands do not carry a 1.x output compatibility promise;
• alpha runtime roots require a new 1.x root instead of an in-place migration.

Use rexecop contracts cli for the command registry. See Public API for the exact surface.

Documentation

Start here

• First run — no-I/O onboarding.
• CLI reference — command contracts and stability.
• Architecture — components and ownership boundaries.

Operate

• Operator runbook — stable read-only operation.
• Lab runbook — fixture-only mechanics and blocked mutation checks.
• Runtime recovery — triage, uncertainty, backup and recovery.
• Storage backends and Secrets.

Integrate and extend

• Public API.
• Profile contract and profile developer surface.
• Execution contract, connector contract, and environment contract.
• GovEngine integration and SCLite integration.
• Scheduler pattern and reaction interpreter.

Review safety and releases

• Safety model, known limitations, and security threat model.
• Stack contract compatibility.
• Release qualification.
• Release evidence and security review.
• Distribution and CHANGELOG.

Development

python scripts/validate_public_truth.py
python scripts/validate_first_run_smoke.py
python scripts/validate_operator_journeys.py
ruff check .
mypy src/rexecop
pytest

The release qualification procedure adds artifact-install, clean-install and supply-chain checks. A separate live GitHub protection check is required before publication.

Security

Report vulnerabilities through the process in SECURITY.md. Do not include credentials, secret values, private connector output or sensitive runtime artifacts in a public issue.

License

MIT — see LICENSE.