Metadata-Version: 2.5
Name: horsegraph
Version: 0.2.0
Summary: Plan node graphs read through Tiny Horse canonical storage and visualized as ClaySpace worlds.
Author: Magus
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: clayspace,dependency-graph,git,planning,tinyhorse
Classifier: Operating System :: OS Independent
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: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# horsegraph

Plan node graphs (`NODE-GRAPH.json`) read through **Tiny Horse** canonical storage and visualized as **ClaySpace** worlds.

- **Tiny Horse** is the source of truth. horsegraph reads the graph from a bound checkout (and can run `tinyhorse doctor` on it), or straight from the canonical bundle in storage (`file:` or `gdrive://`), or from a Drive project by name. When it reads from storage it fetches and verifies the bundle and reads the graph at canonical HEAD, so the view shows what was parked, not unparked local edits.
- **ClaySpace** draws it. Every node is a ClaySpace Cell, every dependency is a Cell with an arrowhead, and the whole graph is a valid `clayspace.world.snapshot`. The HTML is ClaySpace's own self-contained orbit preview, plus a label, hover-detail and legend overlay.

```bash
pip install horsegraph            # add [gdrive] for Drive storage / --project
```

## Use

```bash
# from a Tiny Horse-bound checkout (default graph path docs/runner-gateway/NODE-GRAPH.json)
horsegraph render --checkout . --doctor --out plan.html --world plan.world.json

# straight from canonical storage, no checkout needed
horsegraph render --storage gdrive://FOLDER_ID/Demo.bundle
horsegraph render --project "Demo"            # resolved like `tinyhorse claim`

# plan views
horsegraph next  --checkout .                 # "Needs you now" / "Claude starts next"
horsegraph path  --checkout .                 # critical path to the goal node
horsegraph check --checkout .                 # validate; exit 1 on warnings (e.g. done before its deps)

# any JSON file, no Tiny Horse
horsegraph render --file examples/NODE-GRAPH.json
```

`--graph` changes the path inside the repo; `--ref` reads a tag or commit from storage instead of HEAD.

The ClaySpace world it writes with `--world` opens with the usual tools (`clayspace world inspect`, `clayspace world preview`).

## Reading the 3D view

| Shape | Meaning |
|---|---|
| low green slab | done |
| blue block | open, Claude's (agent) node |
| tall amber tower with a flagpole | open owner action, needs you |
| cyan | on the critical path to the goal |
| pink + sphere | goal node |
| grey, thin | parked (`later`, `after-proof`) |

Flat graphs use columns by dependency depth and rows grouped by track. Graphs with
`parent` relationships use nested regions and a containment outline. Borders and
indentation mean containment; solid arrows mean prerequisites and dashed arrows
mean authored semantic relations. Drag to orbit,
scroll to zoom, and hover a label for the node's title, ancestry, deps and contract
items it advances.

## Graph format

```json
{
  "title": "…", "goal": "G-RELEASE",
  "tracks": {"CLI": "Command Line Interface"},
  "nodes": [
    {"id": "CLI-2", "title": "…", "owner": "agent", "status": "open",
     "deps": ["CLI-1", "CORE-2"], "track": "CLI", "closes": ["C2"]}
  ]
}
```

`owner` is `agent` or `owner`. `status` is `done`, `open`, `later`, `after-proof` or `available-verified`. Extra fields are kept. Cycles, unknown deps and duplicate ids are rejected.

Optional `parent` identifies the node containing a record. Missing or `null`
means a root. Each node has at most one parent; unknown parents, invalid parent
values, and containment cycles are rejected. Containment is independent of
`deps`: it does not change readiness, blocked state, dependency depth, critical
paths, or completion rules. Existing flat graphs retain their layout.

See [nested containment usage and development](docs/NESTED-CONTAINMENT.md) for a
synthetic example, query API, and validation commands. Accepted containment is now
on canonical `main`; `feature/nested-containment-recovery-20261006` preserves the
original accepted feature commit. [Provenance](docs/CONTAINMENT-PROVENANCE.md)
records implementation attribution and the isolated recovery process.
[Checkpoint workflow](docs/CHECKPOINTS.md) describes the required Drive-centered
park, clear, and fresh-restore boundary between finite milestones.

Optional top-level `relations` express authored links such as `challenges`,
`revises`, `influenced_by`, and `supported_by`, with explicit IDs and preserved
evidence/provenance. They never change task readiness or imply confidence/truth.
See [typed relation API, synthetic example, and preview](docs/TYPED-RELATIONS.md).
Typed relations are accepted on canonical `main`; the original reviewed commit
is preserved on `feature/typed-relations-20261006`.

An optional [synthetic inquiry/action example](docs/INQUIRY-BRIDGE.md) records a
bounded proposal, explicit authorization, one manual start, a result and a
subsequent reflection. Its code inspector and read-only spatial history retain
purpose, sources, budgets and unanswered questions. It is an opt-in example,
not part of core graph semantics or an execution engine. This example is included in the source distribution.

## Python

```python
from horsegraph import from_storage, render
graph, prov = from_storage("file:/srv/git/demo.bundle")
print(graph.critical_path(), [n.id for n in graph.ready("owner")])
render(graph, "plan.html", provenance=prov.to_dict(), subtitle=prov.summary())
```

## Release

```bash
python -m build && twine upload dist/*
```

## 0.2.0

Adds nested containment, authored typed relationships, compact readable labels,
full identity/provenance disclosures and robust embedded-canvas initialization.
Relationships remain independent of prerequisite readiness and containment.

Four public JSON examples are included in the wheel under `horsegraph/examples`
and can be located with `importlib.resources.files("horsegraph").joinpath("examples")`.
Optional Python adapters and synthetic tests are included in the source distribution.
Private Woolf source/annotation catalogs are intentionally omitted from public
artifacts; use an explicitly supplied source catalog for archive projections.
