Metadata-Version: 2.5
Name: horsegraph
Version: 0.2.0a2
Summary: Evidence-backed plan graphs, outcome views, and guarded publication journals with Tiny Horse and ClaySpace.
Author: Magus
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: clayspace,dependency-graph,git,planning,tinyhorse
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: clayspace<0.2,>=0.1.3
Requires-Dist: tinyhorse>=0.2.4
Provides-Extra: gdrive
Requires-Dist: tinyhorse[gdrive]>=0.2.4; extra == 'gdrive'
Provides-Extra: test
Requires-Dist: jsonschema>=4.18; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# Horsegraph 0.2.0a2 — alpha

Horsegraph turns dependency plans and reviewed evidence into inspectable outcomes,
ClaySpace views, and durable publication plans. A completed investigation can have
a **failed** result: lifecycle, outcome and permission to act remain separate.

## Install and try it

Use the explicit alpha version. An unqualified installation selects the older
stable version instead.

```sh
python -m pip install horsegraph==0.2.0a2
horsegraph demo --case maintenance --out maintenance-proof
horsegraph inspect --file maintenance-proof/accepted.json --format table
horsegraph render --file maintenance-proof/accepted.json --out maintenance.html --no-overwrite
```

Demo output directories must be new. The maintenance and `--case reed`
demonstrations use saved negative observations and local disposable storage.
They exercise receipt intake, review, upload intent, guarded edits, lost-response
readback and an unchanged repeat. They make no network edits or experiment runs.

## Documentation included with every installation

```sh
horsegraph docs operating
horsegraph docs migration
horsegraph docs contracts
horsegraph docs release
horsegraph schema contracts > horsegraph-contracts.json
```

The wheel carries the operating instructions and JSON Schema contracts offline.
The [PyPI release files](https://pypi.org/project/horsegraph/#files) also provide
the full source distribution, examples and tests.

## Receipt to publication

```sh
horsegraph receipt validate --input receipt.json --evidence-root evidence
horsegraph receipt preview --input receipt.json --review review.json --policy policy.json --file graph.json --evidence-root evidence
horsegraph receipt apply --input receipt.json --review review.json --policy policy.json --file graph.json --evidence-root evidence --out accepted.json --compact
horsegraph inspect --file accepted.json
horsegraph publish plan --journal publication.json --owner publisher --source source.json --snapshot snapshot.json --root artifacts
```

These filenames represent application-supplied data; use the demo for a complete
runnable example. `--compact` stores shared records once using outcome v2.
V1 graphs remain supported. A plan never executes remote work or grants authority.
A trusted adapter performs authorized uploads and guarded edits, then supplies
evidence for reconciliation.

Caption changes can reuse existing references after fresh adapter verification.
Backup obligations survive newer publications. Explicit retirement and restart
preserve the old journal and require evidence that outstanding work cannot
execute later. Read `horsegraph docs operating` before using these commands.

## Graph and Tiny Horse workflows

```sh
horsegraph render --checkout . --doctor --out plan.html --world plan.world.json
horsegraph render --storage gdrive://FOLDER_ID/Demo.bundle
horsegraph render --project "Demo"
horsegraph next --checkout .
horsegraph path --checkout .
horsegraph check --checkout .
```

Install `"horsegraph[gdrive]==0.2.0a2"` for Drive storage. `--file` reads local
JSON; `--graph` selects a repository path; `--ref` selects a stored tag or commit.
The default graph path is `docs/runner-gateway/NODE-GRAPH.json`.
Tiny Horse canonical reads show parked source. ClaySpace produces self-contained
HTML with outcome labels and an accessible evidence table.

```json
{
  "title": "Release plan", "goal": "release",
  "nodes": [
    {"id": "inspect", "title": "Inspect", "owner": "agent", "status": "open"},
    {"id": "release", "title": "Owner decision", "owner": "owner", "status": "open", "deps": ["inspect"]}
  ]
}
```

Cycles, unknown dependencies and duplicate IDs are rejected. Extra fields remain
round-trippable. Legacy `done` means completed; dependency readiness does not imply
a passed outcome or execution permission. `critical_path()` is the longest
dependency chain, not a duration-based schedule.

```python
from horsegraph import from_storage, render

graph, provenance = from_storage("file:/srv/git/demo.bundle")
render(graph, "plan.html", provenance=provenance.to_dict(), overwrite=False)
```

## Support and trust boundaries

This opt-in alpha targets POSIX hosts and Python >=3.10. Durable writes use POSIX
locks and filesystem operations. Windows and multi-host/shared-filesystem
publication are unsupported. A reviewer or source attestor name is an
unauthenticated application assertion; protect policy, accepted graphs and
credentials through application controls.

Render outputs are fully staged, then installed atomically per path. The pair is
not a transaction across power loss. HTML is installed last and embeds its world.
Handled commit failures restore prior files unless another writer replaced them.
`--no-overwrite` uses atomic no-clobber creation against competing creators.

There is no built-in live Page transport. The fixture adapter is for demos.
Production adapters must verify access and bytes, support guarded atomic edits
and discover ambiguous operations rather than retrying blindly.

## Release practice

Build into a new version-specific directory, check metadata, install that wheel
in an isolated environment, run affected tests and record exact hashes. Upload
only the two named artifacts accepted by the release decision, then verify
published hashes. Never upload a directory containing older builds. The source
distribution includes release notes, examples, tests and `BASELINE.json`.
