Metadata-Version: 2.4
Name: vinyasar
Version: 0.4.0
Summary: Policy-driven, evidence-bound self-healing supervision and mutation engine (unified Vinyasar + Yasarda).
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
Requires-Dist: jsonschema<5,>=4.23
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"

# Vinyasar 0.1.0

**Evidence-bound self-healing supervision for Yasarda.**

Vinyasar is the optional automation layer formerly described as “Yasarda
Steward.” It inspects a target, assigns stable issue codes, evaluates a pinned
user policy, invokes only reviewed capability-scoped playbooks, performs a fresh
verification, and writes an append-only canonical JSON run record plus optional
Markdown.

The first release deliberately has one mutating capability:
`yasarda.recover`. It can restore an interrupted journaled Yasarda transaction
through Yasarda's public recovery API. It cannot run commands, author or execute
arbitrary code, install generated playbooks, overwrite divergent content, or
relax Yasarda's filesystem guards.

## Trust model

AI reasoning belongs outside the mutation boundary. A model or agent may propose
a diagnosis, profile revision, explanation, or future playbook. Vinyasar grants
authority only when deterministic evidence, the exact pinned profile, a built-in
reviewed playbook, a named target capability, attempt limits, cooldown, and fresh
post-action verification all agree.

```text
trigger -> inspect -> issue -> policy decision -> bounded playbook -> verify
                                                        |
                                                        v
                                    canonical JSON + Markdown + CloudEvents
```

Authority is monotonic: adapters may remove authority but cannot add it. Unknown
issues use `default_effect`, which can only be `observe` or `escalate`.

## Install

Install the supplied Yasarda 0.3.0 wheel first, then Vinyasar:

```sh
python -m pip install ./yasarda-0.3.0-py3-none-any.whl
python -m pip install ./vinyasar-0.1.0-py3-none-any.whl
```

JSON profiles require no dependency beyond the base install. YAML profiles are
optional and require `vinyasar[yaml]`; JSON remains the canonical portable form.

## Generate and inspect a profile

Profile generation performs read-only setup inspection. It never overwrites its
output file. On a supported POSIX local filesystem it pre-authorizes guarded
recovery of interrupted operations. On iCloud Drive, other detected cloud
storage, remote/FUSE storage, or non-POSIX hosts it generates an escalation-only
rule instead. The target repository, Yasarda journal, and Vinyasar attempt ledger
must all pass that check.

```sh
vinyasar init \
  --repo /path/to/repository \
  --out /path/to/vinyasar-profile.json \
  --schedule "every 30 minutes"

vinyasar validate /path/to/vinyasar-profile.json
vinyasar inspect /path/to/vinyasar-profile.json --trigger manual
```

`validate` prints the exact authority represented by the profile. `inspect` runs
the full reconciliation path in dry-run mode and still emits configured reports.

## Run

```sh
vinyasar run /path/to/vinyasar-profile.json \
  --trigger on_startup \
  --trigger-id launch-2026-09-09T18:00:00Z
```

Schedulers remain external. `launchd`, `systemd`, CI, or an agent invokes the
one-shot command and supplies a stable trigger ID. Reusing the same trigger ID
with the same profile and mode returns the existing append-only report and does
not repeat a repair.

An `approval` policy produces an exact `approval_id` in its decision. A later run
can supply it with `--approve ID`. Changing the issue evidence, playbook,
capability, or profile revision changes that ID.

For MCP clients, start a fixed-profile stdio server:

```sh
vinyasar-mcp --config /path/to/vinyasar-profile.json
```

The MCP tools can inspect, reconcile, and retrieve a report. They contain no
arguments for changing target paths, policy, playbooks, capabilities, or
approvals. If an `approval` rule is used, independently reviewed approval IDs
must be supplied as host startup arguments. The adapter is synchronous and does
not claim experimental MCP Tasks support.

Exit status is 0 for `healthy`, `repaired`, or `dry_run`; 3 for
`approval_required`; 2 for unresolved or failed runs; and 130 for interruption.

## Profile policy

The packaged schemas are available through `vinyasar schema profile` and
`vinyasar schema run`. Unknown fields,
duplicate JSON keys, overlapping issue rules, write directories inside the target
repository, actionable rules without exact capabilities/playbooks, and authority
attached to observe/escalate rules are rejected.

The Yasarda state directory is mandatory and revision-pinned in every normalized
profile. Profile generation resolves Yasarda's configured or default state path
so a later environment-variable change cannot silently select different journals.

Built-in issue codes:

- `INTERRUPTED_OPERATION`: a public Yasarda operation status requires recovery.
- `DIRTY_WORKTREE`: Git reports uncommitted changes; observed by default.
- `UNSUPPORTED_STORAGE`: Yasarda refuses mutation on the detected filesystem.
- `INSPECTION_FAILED`: status could not be established; always escalated by the
  generated profile.

The generated profile enables manual, startup, and failed-execution triggers.
A recorded scheduled expression is metadata for the external scheduler; Vinyasar
does not reinterpret or execute natural-language schedules.

## Reports and events

Every completed run writes `vinyasar-RUN_ID.json` with mode 0600. Markdown is
derived from that JSON. Existing report paths are never overwritten. Each record
contains CloudEvents 1.0-compatible issue, policy-decision, action, and run
envelopes suitable for future MCP Task or A2A adapters.

No repository source contents are collected by Vinyasar. Yasarda receipts omit
the source bytes retained privately in recovery journals. Report retention is
recorded in configuration but deletion is not automated in this release.

## Limits

- Vinyasar is a supervisor, not an OS sandbox or a semantic repair oracle.
- Only the built-in recovery playbook is executable in 0.1.0.
- Attempt reservations are persisted before mutation; crashes consume an attempt.
- Maximum attempts apply to unchanged evidence. Changed evidence produces a new
  issue identity and requires a fresh policy decision.
- MCP Tasks and A2A are adapter targets, not Vinyasar's source of truth.
- Cryptographic attestation, OPA/Wasm policy backends, SARIF, and OpenTelemetry
  exporters are intentionally outside this minimal trusted core.
