Metadata-Version: 2.4
Name: rexecop
Version: 1.0.0rc1
Summary: Regulated Execution Operations control-plane for profile-defined workflows bound to GovEngine and SCLite.
Project-URL: Homepage, https://github.com/rozmiarD/RExecOP
Project-URL: Repository, https://github.com/rozmiarD/RExecOP
Project-URL: Documentation, https://github.com/rozmiarD/RExecOP#readme
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: govengine==1.0.0rc1
Requires-Dist: pyyaml>=6.0
Requires-Dist: sclite-core==2.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: sclite
Requires-Dist: sclite-core==2.0.0; extra == 'sclite'
Description-Content-Type: text/markdown

# RExecOp

[![CI: pytest](https://github.com/rozmiarD/RExecOP/actions/workflows/ci.yml/badge.svg)](https://github.com/rozmiarD/RExecOP/actions/workflows/ci.yml)
[![Package: rexecop 1.0.0rc1](https://img.shields.io/badge/package-rexecop%201.0.0rc1-blueviolet.svg)](https://pypi.org/project/rexecop/1.0.0rc1/)
[![Python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
[![Dependency: GovEngine](https://img.shields.io/badge/dependency-GovEngine-informational.svg)](https://github.com/rozmiarD/GovEngine)
[![Dependency: SCLite](https://img.shields.io/badge/dependency-SCLite-informational.svg)](https://github.com/rozmiarD/SCLite)
[![Profile: tecrax](https://img.shields.io/badge/profile-tecrax-informational.svg)](https://github.com/rozmiarD/tecrax)
[![Status: release candidate](https://img.shields.io/badge/status-release%20candidate-green.svg)](#status)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

**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

| Item | Value |
| --- | --- |
| Current source line | `1.0.0rc1` |
| Main branch | May include unreleased changes listed under `CHANGELOG.md` / Unreleased |
| Maturity | **release candidate** — stable read-only core with documented limits |
| Delivery | `1.0.0rc1` release candidate through the protected OIDC release workflow |
| Tests | CI reruns the current suite; `pytest -m delivery` runs the sign-off scope |
| Latest PyPI | [`rexecop==1.0.0rc1`](https://pypi.org/project/rexecop/1.0.0rc1/) |
| Exact dependencies | Public `govengine==1.0.0rc1`, public `sclite-core==2.0.0` (see `pyproject.toml`) |
| Stack compatibility | [`docs/stack-contract-compatibility.md`](docs/stack-contract-compatibility.md) |
| Default posture | `stable_read_only`; `apply` / `recovery` execution is mechanically blocked even after GovEngine allow |

## 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.

```text
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)
```

| Layer | Responsibility |
| --- | --- |
| **Profiles** | Intents, workflows, connector contracts, declarative validation rules |
| **RExecOp** | Runner: lifecycle, planning, step dispatch, pause/resume/retry, queue/lock; **projects** completed operations into SCLite bundles (does not decide policy) |
| **GovEngine** | Governance: admission and runner request/receipt **contracts** — does not execute steps or emit SCLite files |
| **SCLite** | Proof: auditable artifacts, scoped tickets, receipt-bounded evidence, review bundles |

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`](https://github.com/rozmiarD/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:

```bash
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](docs/distribution.md) for core wheels, Git installs,
private indexes, and the separate Tecrax consumer path.

From source (development):

```bash
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:

```bash
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

```bash
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](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](docs/cli-reference.md).

| Group | Commands |
| --- | --- |
| Runtime readiness | `init`, `doctor`, `env lint`, `version` |
| Secrets | `secrets doctor`, `secrets suggest-ref` |
| Profile developer | `profile lint`, `profile manifest`, `profile harness`, `profiles list/show`, `connectors list/show`, `capabilities list` |
| Action metadata | `action list`, `action show`, `action preview`, `action policy-preview`, `action validate`, `action diff`, `action configure` |
| Catalog | `targets list/show`, `operations list`, `operations explain`, `operations unavailable` |
| Pre-run inspection | `policy explain`, `governance controls`, `operation explain`, `operation review`, `operation diff`, `runbook show` |
| Runtime triage | `runtime status`, `runtime reconstruct-status`, `ops`, `explain-error`, `dead-letter list/show`, `locks list`, `runtime recover`, `backup create/restore`, `watchdog manual-record` |
| Observability | `observability logs list`, `observability diagnostics` |
| Lifecycle | `plan`, `approve`, `start`, `pause`, `resume`, `cancel`, `retry`, `rollback`, `validate`, `escalate`, `status`, `history` |
| Scheduling | `queue`, `worker run`, `trigger` |
| Reactions | `reaction-plan`, `reaction-start`, `reaction-replay`, `reaction explain`, `reaction-proposal-validate`, `reaction-proposal-review`, `reaction-proposal-submit` |

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](docs/public-api.md).

## Development

```bash
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

| Document | Topic |
| --- | --- |
| [docs/public-api.md](docs/public-api.md) | Supported Python imports, CLI stability, schema and runtime-root compatibility |
| [docs/cli-reference.md](docs/cli-reference.md) | Complete CLI command reference |
| [docs/first-run.md](docs/first-run.md) | No-I/O onboarding: init, doctor, lint, plan |
| [docs/operation-lifecycle.md](docs/operation-lifecycle.md) | States, lifecycle orchestration, queue/lock |
| [docs/runtime-recovery-ops.md](docs/runtime-recovery-ops.md) | Triage, explain-error, recovery, backup and watchdog manual-record |
| [docs/profile-developer-surface.md](docs/profile-developer-surface.md) | Profiles/connectors/capabilities discoverability and extension manifest |
| [docs/secrets-operator.md](docs/secrets-operator.md) | `secrets doctor`, ref resolution and file policy |
| [docs/reaction-interpreter.md](docs/reaction-interpreter.md) | Deterministic reaction DSL and CLI |
| [docs/architecture.md](docs/architecture.md) | Layer boundaries and execution path |
| [docs/stack-contract-compatibility.md](docs/stack-contract-compatibility.md) | Cross-repo contract matrix and readiness labels |
| [docs/operator-scheduler-pattern.md](docs/operator-scheduler-pattern.md) | Host-owned scheduling with worker/systemd |
| [docs/govengine-integration.md](docs/govengine-integration.md) | Governance port and apply gating |
| [docs/sclite-integration.md](docs/sclite-integration.md) | Artifact emission and authority model |
| [docs/evidence-model.md](docs/evidence-model.md) | Internal events vs SCLite truth |
| [docs/profile-contract.md](docs/profile-contract.md) | Profile layout and entry points |
| [docs/connector-contract.md](docs/connector-contract.md) | `http_api`, secrets, error taxonomy |
| [docs/execution-contract.md](docs/execution-contract.md) | ExecutionRequest/Receipt, bounded output |
| [docs/environment-contract.md](docs/environment-contract.md) | Target, group, and connector semantics |
| [docs/operator-catalog.md](docs/operator-catalog.md) | Target catalog, operation projection, applicability and drift binding |
| [docs/storage-backends.md](docs/storage-backends.md) | File vs SQLite boundaries |
| [docs/safety-model.md](docs/safety-model.md) | Hard safety rules and operator posture |
| [docs/known-limitations.md](docs/known-limitations.md) | Alpha scope and explicit non-claims |
| [docs/distribution.md](docs/distribution.md) | Wheels, Git install, private index |
| [docs/alpha-sign-off.md](docs/alpha-sign-off.md) | Automated and human sign-off gates |
| [docs/adr-001-http-action-identity.md](docs/adr-001-http-action-identity.md) | HTTP action identity ADR |
| [OPERATOR_LAB_RUNBOOK.md](OPERATOR_LAB_RUNBOOK.md) | Lab checklist and E2E walkthrough |
| [OPERATOR_RUNBOOK.md](OPERATOR_RUNBOOK.md) | Installation, secrets, workflows, troubleshooting |
| [CHANGELOG.md](CHANGELOG.md) | Release history |

## Related repositories

| Repository | Role |
| --- | --- |
| [GovEngine](https://github.com/rozmiarD/GovEngine) | Governance kernel and admission contracts |
| [SCLite](https://github.com/rozmiarD/SCLite) | Auditable contract lifecycle and review bundles |
| [tecrax](https://github.com/rozmiarD/tecrax) | Tecrax domain profile and local-fixture package |

## License

MIT — see [LICENSE](LICENSE).
