Metadata-Version: 2.5
Name: horsegraph
Version: 0.3.0.dev26
Summary: Plan node graphs read through Tiny Horse canonical storage and visualized as ClaySpace worlds.
Project-URL: Homepage, https://pypi.org/project/horsegraph/
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.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

Install this development release from PyPI with
`python -m pip install horsegraph==0.3.0.dev26`.
The default stable PyPI release may be older and lack these commands.
Then start with `horsegraph examples` for complete offline Enyalcalma demos.

## 0.3.0.dev26

Record and inspect attributed source/claim assessments with `horsegraph assessments` and Enyalcalma Details. Evidence bindings expose changed records; scope-aware labels preserve differing assessments without declaring a logical contradiction. Blank identity strings are invalid; use null for unknown identity or scope. Current means bound records are unchanged, not an authenticated source or correct assessment. External source bytes require separate `verify`; its existing contract is unchanged. No automated investigation, signature authentication or truth verdict is supplied.

## 0.3.0.dev25

**CLI compatibility change:** partial byte verification now exits 1 unless you explicitly pass `--allow-partial`. JSON `ok:true` still means byte agreement and can accompany exit 1; use `success` for CLI policy and `complete` for anchored v2 reference-scope completeness. Prefer `--reference macbeth` or `--reference typescript-to-rust`. No mode authenticates authorship or establishes source truth. See Verification coverage and sharing below for exact exit codes.

This release bounds graph-file reads, makes maintained text I/O locale-safe, repairs offline documentation navigation, and accounts for all five graph statuses without changing their meanings.

## 0.3.0.dev24

Adds versioned content-bound reference verification with independent digest pins,
compatible v1 required-ID contracts, and complete offline Macbeth and TypeScript/
Rust verification examples. Every present byte claim is checked; trusted required
claims bind IDs to exact source/range/text hashes. Checksums do not establish
source authenticity or semantic truth; an unanchored editable reference can be
replaced alongside its graph.

Fixes queued help-dialog focus restoration, reports unsupported owners and rejects
ignored source-option combinations. Adds explicit UTF-8 reads, bounded explanation
inputs, opt-in generated-path redaction, installed documentation and script-hash
CSP. Enyalcalma stays read-only and complete-input export disclosure remains.

Removes repeated connection-label counting and includes reproducible bounded
performance results. See `horsegraph docs performance` for measured sizes, ranges,
failed setup probes and limitations. Physical-iPhone and VoiceOver acceptance
remain open; desktop Chrome/touch emulation does not close them.

## 0.3.0.dev23

Fixes graph initialization when literal HTML comment/script text appears in node
labels, in both standalone graphs and Enyalcalma maps. Original text and IDs are
preserved. Invalid goal types now produce a handled graph error (CLI exit 2);
missing and null goals retain their existing behavior. Enyalcalma remains read-only.

Adds browser control regressions and public API/CLI goal validation regressions.
Desktop Chrome verification does not establish physical-iPhone or VoiceOver
acceptance; Safari automation remains unverified.

## Quick start (installed package)

```sh
horsegraph examples                                   # list the complete examples
horsegraph examples macbeth --out "Macbeth example"   # copy one into a new directory
cd "Macbeth example"
horsegraph enyalcalma --file ENYALCALMA-MACBETH.json --out regenerated.html
horsegraph verify --file ENYALCALMA-MACBETH.json --sources-dir sources/macbeth --reference macbeth
```

Open `macbeth.html` in a browser. `regenerated.html` is byte-identical to it, and
`verify` checks that each quotation is exactly the stated bytes of the retained
edition (byte-exactness only; meaning and source authenticity are not checked).
`README.md` and `GUIDE.md` in the copy explain the evidence and its limits;
`horsegraph examples typescript-to-rust --out "Port example"` copies the second
example. Nothing here needs a repository, network access or credentials.

Read installed documentation offline with `horsegraph docs` (guide),
`horsegraph docs graph`, `horsegraph docs enyalcalma`, `horsegraph docs symbols`,
or `horsegraph docs plain-english`. Paths such as `docs/ENYALCALMA.md` also name
files in the source distribution; they are not wheel-relative filesystem links.

## What it is, and installing it

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            # stable release; add [gdrive] for Drive storage
# For a development build, install its explicitly selected version or candidate wheel.
```

## Use

```bash
# from a TinyHorse-bound checkout, with an explicit graph path
horsegraph render --checkout . --graph NODE-GRAPH.json --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 TinyHorse service/project or credentials required
horsegraph render --file my-graph.json
```

`render` and `enyalcalma` require new output paths, including `--world`.
`--graph` names a relative path resolving 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`).

## Enyalcalma (development prerelease)

Read an interpretation beside its linked source, with authored challenges and
competing responses. The HTML works offline and leaves its input unchanged:

```sh
horsegraph enyalcalma --file my-comparison.json --select interpretation --out comparison.html
```

Existing NodeGraph files work without a comparison mapping; no roles are inferred.
The reading contract and examples (`docs/ENYALCALMA.md`) explain optional display
roles, provenance, missing evidence and keyboard-accessible inspection. All assets
and complete offline example packs are included in the wheel. Single-file example
graphs (including the Anakin story and the cache-decision comparison) are installed
under `importlib.resources.files("horsegraph") / "examples"`; `horsegraph examples`
prints that directory and describes each file.
This command is a development checkpoint, not part of published 0.2.1.

## 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 `horsegraph docs graph` for containment, source selection and provenance.

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 relationships" in `horsegraph docs graph`.

An optional synthetic inquiry/action example ("Optional inquiry example" in `docs/GRAPH-REFERENCE.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

Run the Python, regeneration and complete browser gates in `docs/TESTING.md`,
then build and verify both distributions. Playwright is an optional maintainer
dependency declared in package.json. Publication requires separate approval.

## Graph capabilities

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.

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.
Archive projection adapters require an operator-supplied source catalog; they
are optional source-distribution examples, not services or bundled reading packs.

## Independent connection layers

Independent connection layers ("Connections" in `docs/GRAPH-REFERENCE.md`) add visibility controls
for containment, prerequisites and semantic relationships, relation-type filters,
and selectable connections with complete endpoint/provenance details. These layers are included in the development prerelease.


### Macbeth reading example

Compare a passage with what happens in the play, follow the characters’
relationships, then consider two optional readings. Covers Acts 1–2 with spoilers
through Duncan’s murder. The exact Project Gutenberg edition and license ship
with the example; no online service is required.

Copy it with `horsegraph examples macbeth --out "Macbeth example"` (see the quick
start above). The reading guide is in `docs/ENYALCALMA.md` and the edition details
in `examples/sources/macbeth/README.md`. The current hosted demo is updated
separately; the copied example generates a local review artifact.

## From a source checkout

The source distribution and a repository checkout keep the example graphs at
`examples/`, so these work from its root (an installed package has no such folder;
use the quick start above):

```sh
horsegraph render --file examples/NODE-GRAPH.json
horsegraph enyalcalma --file examples/ENYALCALMA-CACHE.json --select interpretation --out comparison.html
horsegraph enyalcalma --file examples/ENYALCALMA-MACBETH.json --out macbeth.html
horsegraph enyalcalma --file examples/ENYALCALMA-ANAKIN.json --select fear --out story.html
```

## Offline verification limits

`verify` accepts lowercase 64-digit SHA-256 hashes for source and excerpt claims.
Malformed hashes produce a structured provenance failure, never a traceback.
With `--json`, a graph without byte-range claims returns a JSON report with
`status: "no_byte_claims"`, `ok: false`, and exit code 2; text mode retains its
explanation on stderr. A completed comparison exits 0 on success or 1 on failure.

Source loading is limited to 64 MiB per file, 256 MiB total bytes read, and 1,024
files across direct sources and recursive directory sources combined. Duplicate
content still counts toward the read budget. Oversized files now fail explicitly
instead of being silently skipped by directory scanning. Reads remain bounded if
files grow. Direct source symlinks and a symlink directory root are refused;
recursive symlinks and special files are ignored. No sources are fetched.

## Verification coverage and sharing

`verify` checks byte claims, not truth or whole-graph completeness. Its `ok:true`
means the supplied claims passed; `coverage` reports records, claims, verified
passages and uncheckable records. Partial or malformed byte claims fail. Legitimate
non-quotation records and whole-file references without ranges remain uncheckable.
Without an independent v2 reference, wholly removed or coherently repointed claims cannot be ruled out. Prefer `--reference macbeth` or `--reference typescript-to-rust` from a trusted installation. For external v2 references, retain the manifest SHA-256 independently and use `--expect-claims reference.json --expect-sha256 HEX`; deriving a digest from the file being reviewed provides no independent trust.

Compatibility change in 0.3.0.dev25: `ok` still means all present/required byte checks passed. `complete` means every required v2 content binding passed against a verified anchor, **only within that reference scope**. `coverage.state` is `reference_complete`, `partial`, or `failed`; `success` is the CLI exit policy. Exit 0 requires `complete:true` or explicit `--allow-partial` with `ok:true`. Exit 1 means a failed check or partial coverage without opt-in; exit 2 means invalid input or no byte claims. `--allow-partial` never hides failures. The API preserves its `ok` contract and reports `complete:false` because it does not independently establish the caller's trust anchor.

V1 references require IDs only and cannot bind their content, even when their file digest is pinned. Unanchored v2 references bind content to the supplied editable manifest but cannot establish its integrity. Both remain partial. Extra recognized byte claims are checked; legitimate uncheckable/nonquotation records outside the reference scope do not make a valid pinned scope incomplete. Neither completeness nor source-byte agreement establishes authenticity, authorship, semantic truth, or whole-graph completeness.

`next` reports unsupported owners and exits 1 on graph warnings. It exposes
`available-verified` records separately: they are neither ready tasks nor `done`,
and do not satisfy prerequisites. No owner/status aliases are inferred. `path`
returns the longest dependency chain to the goal, not a time estimate; `path
--json` emits it as JSON.

`--ref` is for `--storage`/`--project`; `--doctor` is for checkouts. `--file` cannot
be combined with either option or `--graph`. The legacy checkout default path is
retained for compatibility; use explicit `--graph NODE-GRAPH.json`, `--file`, or
`horsegraph examples` for discovery.

Generated HTML normally retains the supplied input filename/path in provenance.
Use `render --file ... --redact-local-path` or `enyalcalma --file ...
--redact-local-path` to retain only the basename in generated source metadata.
This does not redact paths or private content authored inside the input: the
complete input, including hidden records and provenance, is still embedded.

Self-contained readers use script-hash CSP and deny network connections. Input
escaping remains essential; this defense does not authenticate text or establish
that earlier parser-initialization failures were code execution. Offline graph
controls remain available. Browser/runtime coverage is recorded separately.

TinyHorse remains an installed Python dependency even for `--file`; no TinyHorse
service, project or credentials are needed for that route. ClaySpace's exact pin
is intentional for renderer compatibility and reproducibility. The package does
not claim a checked typing contract or ship `py.typed`.

Content-bound references are available in 0.3.0.dev24:
`horsegraph verify --file ... --sources-dir ... --reference macbeth` pins all nine
IDs to original source/range/quotation hashes through a verified installation.
For external files, use `--expect-claims reference.json --expect-sha256 HEX` with
an independently retained digest. V1 ID-only contracts remain compatible. V2
schema, trust limits and exit states are in `horsegraph docs graph`; copied packs
include offline instructions and references. Checksums do not prove authorship or
semantic truth, and a reference supplied beside a graph is not self-authenticating.

Measured performance and reproducible bounded benchmark instructions: `horsegraph docs performance`. Full samples and scripts are included in the source distribution.

## 0.3.0.dev25 input and accounting fixes

Graph file inputs now require a regular non-symlink UTF-8 file no larger than 64 MiB. `check`, `render`, `enyalcalma`, `verify`, `next`, `path`, `NodeGraph.load` and checkout loading share this contract. Git-storage graph blobs are size-checked before capture and symlink blobs are refused. Reads are bounded if a file grows; this is not a complete filesystem sandbox against ancestor-directory or concurrent replacement races. In-memory JSON bytes also require UTF-8 and the same size limit. Output symlink refusal is unchanged.

`stats` includes a disjoint count for each of the five statuses; their sum equals `nodes`. Owner/readiness counts overlap these totals. `next` reports each blocked prerequisite's exact status; `available-verified` remains neither done nor ready.

## Attributed assessments

Inspect recorded source-identity and claim assessments offline with `horsegraph assessments --file GRAPH.json --json`. Read them under record Details in Enyalcalma. They preserve examiner attribution, methods, evidence for/against, scope, uncertainty and version bindings. Matching bindings do not authenticate an assessor or establish truth. `horsegraph docs graph` describes the schema, staleness limits and inspection exit codes. Existing `verify` byte/coverage/success semantics are unchanged.
