Metadata-Version: 2.4
Name: vinyasar
Version: 0.5.0
Summary: Policy-driven, evidence-bound self-healing supervision over the Yasarda mutation engine.
Author: Mitchell Davis Burns / EVERPLAY
License-Expression: LicenseRef-Proprietary
Keywords: automation,self-healing,agents,yasarda,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: yasarda<0.6,>=0.5
Provides-Extra: yaml
Requires-Dist: PyYAML<7,>=6.0.2; extra == "yaml"
Provides-Extra: mcp
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# Vinyasar: Policy-Driven Self-Healing Supervision for Yasarda

Experimental package. Policy-driven, evidence-bound self-healing supervision and mutation engine.

## Installation

```sh
pip install vinyasar
# with optional YAML profile support:
pip install "vinyasar[yaml]"
```

> **Yasarda is a dependency**: `vinyasar` depends on the `yasarda` package (`yasarda>=0.5,<0.6`) and no longer embeds a copy. Installing `vinyasar` installs `yasarda`, which provides the `yasarda` and `yasarda-mcp` commands. There is one engine at one version.

## Public Feature Coverage

Vinyasar provides two console scripts, and its `yasarda` dependency provides two more:
- `vinyasar`: The primary self-healing controller CLI.
- `vinyasar-mcp`: The MCP server for Vinyasar. `--config P` serves one pinned profile; `--profiles-dir DIR` serves every profile file in a host-owned directory from one host, where tools take a `profile` name chosen from the host-fixed set (`list_profiles` names them), and approvals stay with the host (`--approve`).
- `yasarda` (from the `yasarda` package): The Yasarda engine CLI for low-level structural mutation.
- `yasarda-mcp` (from the `yasarda` package): The MCP server for Yasarda.

It also provides two subcommands under `vinyasar` for configuration hygiene and host verification:
- `vinyasar schema`: Outputs the JSON schema for validation of `vinyasar.json`/`vinyasar.yaml` profiles.
- `vinyasar doctor`: Verifies the health and presence of the required environment and evaluator constraints.

### Basic Example

```bash
# Generate a profile for an app repository: its test suites become test_run
# checks (each program granted by name), failing checks route to reviewed
# Yasarda remediations by approval only, and no evaluator is configured.
vinyasar init --kind app-repo --repo ~/work/my-app --out ~/profiles/my-app.json \
  --catalog ~/profiles/my-app-remediations --test-command "cargo test --offline"

# Check the profile (and that every named remediation exists in the catalog)
vinyasar doctor ~/profiles/my-app.json

# Run once; exit 3 means approval is required, and the run record names the
# exact plan and its approval ID
vinyasar run --trigger manual --trigger-id round-1 ~/profiles/my-app.json

# Run again with the approval for that one plan
vinyasar run --trigger manual --trigger-id round-1-approved --approve APPROVAL_ID ~/profiles/my-app.json

# The profile and run-record schemas
vinyasar schema profile
vinyasar schema run
```

Plain `vinyasar init` (kind `repo`) generates the conservative operational
profile: recovery of interrupted Yasarda operations, nothing else.

`vinyasar conformance run` checks this installation against the packaged
conformance set, byte for byte; `src/vinyasar/conformance_set/README.md` is the
protocol a second implementation follows to be held to the same outputs.

## Architecture

Vinyasar acts as an **externally scheduled, trigger-driven reconciler**. Schedule expressions (such as crons) are owned by external schedulers (e.g., `launchd`, `systemd`, or CI pipelines). When invoked, Vinyasar operates as a bounded one-shot process to inspect the target repository, consult the Yasarda engine, execute allowed playbooks, and exit, leaving behind a cryptographic-like ledger of actions taken.

## Evaluator Prerequisite

For optional policy braking and advisory evaluations during operation, Vinyasar delegates to the `jev` evaluator. If these features are utilized, it requires **`jev >=0.6.2,<0.7.0`** to be available on the host `PATH`.

The jev state ceiling is a word, not a free byte count. Each word is one payload:

- `standard` — 64 KiB of issue metadata. This is the default when the word is omitted, and the only payload `vinyasar inspect` and `vinyasar run` send. `--state-cap` on those commands must be `standard` or omitted, and a profile word other than `standard` is rejected before a run starts. Passing `--state-cap` still requires `spec.evaluator`.
- `inventory` — 1 MiB. A path census: relative paths and decimal sizes, not file bodies. `vinyasar inventory --repo PATH` builds it in process and does not call `jev`.
- `windows` — 4 MiB. One verified UTF-8 slice per path. `vinyasar windows --repo PATH --spans FILE` checks each span against the file's own bytes. It is not a whole file, and the file read limit stays 8 MiB. It does not call `jev`.

`vinyasar judge inventory` and `vinyasar judge windows` are the only commands that send those payloads to `jev`. They take the same builder flags, a required `--question`, and at least one `--option KEY=DESCRIPTION`. They do not run a playbook and they do not restore a journal. `vinyasar doctor` prints the profile word and does not accept `--state-cap`. There is no exponent and no unlimited word.
