hypgraph 0.5.2__tar.gz → 0.6.0__tar.gz

{hypgraph-0.5.2 → hypgraph-0.6.0}/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 0.6.0 — 2026-10-26: the HypGraph UI, live swarm observability, an example per profile
+
+The Atlas becomes **HypGraph**: one app for every profile, in each profile's own words, that watches a swarm
+work as it happens and replays any finished run. The design record is `docs/ui-plan.md`. Nothing in the record
+format changes; bundles gain optional fields that sit outside the hash chain.
+
+**The HypGraph UI**, which replaces the Atlas:
+- **Eight views in each profile's own words:** Overview, Live, Pipeline, Graph, Evidence, Work orders, Audit log and
+  Report. A software investigation shows Requirements and Verifications; a trading one shows Theses and Positions.
+- **Overview** has KPI tiles, the completion criteria, each question's stage, a "needs attention" list and recent
+  activity. Attention covers stale evidence, contested claims, premises that fell, leases held past their time,
+  returned orders, overclaims refused and a broken chain.
+- **Pipeline** is a swimlane of the profile's stages, with each gate met or not, its evidence, and what would meet it.
+- **Live** shows seats, the record growing and the event stream. It follows `/api/graph/stream` and falls back to
+  polling on hosts without it. Any run plays back with play, pause, scrub and speed controls.
+- **Drawers:** a node's drawer gives its standing, fields, links both ways, provenance and what would be at risk if
+  it fell. A question's drawer gives its stage and gates.
+- **Enterprise:**
+  - light by default, with dark one key away;
+  - WCAG AA text contrast in both themes, checked by a test;
+  - every screen is a URL, and Back and Forward work;
+  - ⌘K search over views, investigations and nodes, plus keys 1–8, `/`, `t` and Esc;
+  - CSV export for tables, PNG and JSON for the graph, Markdown and print-to-PDF for the report, and the bundle;
+  - the hash-chain badge, read-only, with no build step.
+- **Compatibility for one release:** `atlas.js` and `atlas.css` load the new app, `HypAtlas` is an alias of
+  `HypGraph`, and the `--hg-*` theme tokens still apply. Routes a host doesn't serve are hidden rather than failing,
+  so PegasusDMZ's older API still works.
+- `dev/ui_smoke.py` renders every view of five profile fixtures in both themes, plus an Atlas-style page, in headless
+  Chrome. CI runs it.
+
+**Live observability for a running swarm** (with hypswarm ≥ 0.1.0a7's telemetry):
+- **`hypgraph serve` streams a swarm's telemetry.** hypswarm writes `<record>.telemetry.jsonl` beside the record: every
+  model call, tool call, work order and scheduler decision, as spans. The server serves it at `GET /api/graph/telemetry`
+  (paged by byte offset) and tails it into `/api/graph/stream` as `telemetry` events. Ids become `<seq>:<offset>` so a
+  reconnect resumes both. A sidecar that appears after the server starts is picked up, and `--telemetry FILE` /
+  `--no-telemetry` override the default. Telemetry is shown, never trusted for standing.
+- **The Live view shows the swarm working:**
+  - each seat's call in flight (the model it's calling or the tool it's running, with seconds elapsed), and its calls,
+    tokens, cost and errors;
+  - KPI tiles for model calls, tokens in → out and cached, spend, tool calls, errors, and budget used against the run's cap;
+  - an event stream merging the record and telemetry, with a filter;
+  - a trace for any work order, showing each model and tool call on a timeline;
+  - alerts: a tool failing three times in a row, a seat repeating an identical tool call, failed model calls, the
+    budget passing 80 %;
+  - status from the run's own start and end ("Run ended · settled").
+
+  A record opened before its swarm starts picks the investigation up when it begins. Replay scopes telemetry to the
+  replay position. Overview's spend falls back to telemetry when the ledger isn't metered.
+- `dev/ui-fixtures/swarm.*` holds a real scripted swarm's bundle and telemetry, and the smoke check requires its trace.
+
+**What the UI needs from the engine:**
+- **Each profile speaks its own words.** `Profile.labels` gives the short noun a screen shows for each node type: a
+  software question is a **Requirement**, a trading hypothesis a **Thesis**, a decision a **Position**, an
+  optimization result a **Solution**. `profiles.view(pid)` returns what a UI needs: the labels for every node type
+  (the kernel's word where the profile has none), the meaning of each type, and the workflow's stages, gates and
+  report name. The `@1` profiles are frozen and keep the kernel's words. The labels are display only.
+- **A bundle carries the workflow views.** Each investigation's `derived` now has `profile`, `stages`, `completion`,
+  `board` and `orders` beside the report, so a viewer shows stages and gates without the engine. As before, derived
+  views are outside the hash chain and never trusted.
+- **Watch a record live.** `GET /api/graph/stream?inv=&after=` pushes every event as it is written, as Server-Sent
+  Events. It includes writes from another process on the same file, so a swarm running against the record is
+  watched as it works. Ids are event seqs, so a client resumes with `Last-Event-ID`. A comment line every 15 s keeps
+  proxies open, and `max_seconds` bounds a read.
+- `GET /api/graph/profile?inv=` gives the investigation's profile as a UI speaks it.
+- "Atlas" is now the HypGraph UI in the server, the CLI, the README and the skill.
+
+**A live example per profile on hypgraph.com:**
+- **Five live examples.** `/examples/` has one page per `@2` profile: scientific, software, trading, knowledge and
+  optimization. Each is a HypSwarm run on a real record that opens on its live replay. You see the seats take work
+  orders, model and tool calls in flight, writes refused and rewritten, and reviews landing, then you can explore the
+  pipeline, graph, evidence and report. The pages load offline from their bundles and re-verify each hash chain in
+  the browser. `dev/site_examples.py` rebuilds them from HypSwarm's scripted examples, pacing each reply 0.35–1.4 s,
+  and every page says so.
+- **A bundle can carry the run's telemetry.** `export(inv, telemetry=path)` and `hypgraph export --telemetry [FILE]`
+  (default `<db>.telemetry.jsonl`) add a swarm's sidecar for replay. It is outside the hash chain:
+  `verify_bundle` and `from_bundle` ignore it, and the UI labels it "not hash-chained". It is off unless asked for,
+  because a sidecar names a run's models, seats and spend.
+- **`play` opens on the replay.** The `play` mount option, or `#view=live&play=1`, opens the Live view and plays the
+  run from its first event. With reduced motion requested, it shows the finished run with Play one click away.
+- **A refused write is not an error.** In the Live view, a tool call the record refused counts as "refused by the
+  record", with its reason: amber on the seat, in the stream and in the trace. Errors count real failures only.
+- **The site's Atlas page is replaced.** The UI is served from `/app/`, `/explore/` opens any bundle full screen, and
+  `/atlas/` forwards there (keeping `?bundle=`, the hand-over from `/verify/` and the fragment). The home page embeds
+  the app directly. `/verify/` says when a bundle carries telemetry and opens bundles in HypGraph.
+- **A narrow layout.** Below 760 px of its own width (a phone, or a narrow frame), the app's sidebar becomes a strip of
+  tabs and the top bar wraps. It uses a container query, so an embed sizes it, not the window.
+- The smoke check also renders the site: each example opens replaying with its chain verified, plus the home page,
+  the explorer, the `/atlas/` forward and the gallery (106 pages).
+
+## 0.5.3 — 2026-10-26: results that name no file can go stale
+
+- **A result that names no file it read can go stale.** Under a workflow (`@2` profiles), a result whose run has no
+  `uses` link was fresh forever, however the files changed. It now goes STALE once an input file of its
+  investigation is replaced or withdrawn after the result was written ("it names no file it read, and A1 changed
+  after it was written"), and claims resting only on it with it. A file registered on another question only
+  (`part_of`) doesn't count against it; run outputs and page excerpts never do; a result written after the change
+  is fresh; a result that names its files keeps the usual rule (only those files count). Ordered by the event log,
+  not timestamps. Records without a workflow are unchanged. Measured on 851 results in HypSwarm's stored study
+  records: none changes standing.
+
 ## 0.5.2 — 2026-10-26: freshness for sources, stale evidence in the report
 
 For P3 (the change suite and the instruments in HypSwarm), the record had to know when a *page* moved, not only a

{hypgraph-0.5.2 → hypgraph-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypgraph
-Version: 0.5.2
+Version: 0.6.0
 Summary: The evidence layer for AI research agents: a hash-chained research record that checks every claim as it is written and derives how well each is known.
 Project-URL: Homepage, https://hypgraph.com
 Project-URL: Documentation, https://hypgraph.com/engineers/
@@ -152,7 +152,8 @@ record behaves exactly as before.
 met, every gate MET / NOT MET with what would meet it); `GET /api/graph/stages`; MCP tool `stage`. A workflow
 widens what puts dependants AT RISK — `uses` (a corrected data file, a superseded diff or instance), `cites` (a
 withdrawn source) — and evidence goes **stale** when the artifact it used is superseded or its `valid_until` has
-passed. An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
+passed. A result whose run names no file it read goes stale when an input file of its question changes after it:
+nothing shows it read the new version (name the files with `uses` and only those count). An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
 verified failure each complete a question the gates alone never would.
 
 Profiles are versioned and frozen: a record written under `trading@1` means the same thing in a year, and the `@1`
@@ -193,9 +194,16 @@ with g.writing_for(task_id):                                # every event carrie
 - **Multi-agent:** give each agent its own author name. Make your critic agents reviewers. Have your job runner
   write as the instrument, so its runs count as recorded, not reported.
 - **Your web framework:** `hypgraph.server.dispatch(graph, method, path, query, body)` is the JSON API, and
-  `hypgraph.ui.static_dir()` is the Atlas explorer to mount next to it.
+  `hypgraph.ui.static_dir()` is the HypGraph UI to mount next to it.
+- **Watching it live:** `GET /api/graph/stream?inv=` pushes every event as it is written (Server-Sent Events,
+  resumable with `Last-Event-ID`), including writes from another process on the same file, such as a swarm running
+  against the record. `GET /api/graph/profile?inv=` gives the investigation's profile as a UI speaks it: each node
+  type's label ("Requirement", "Thesis"), the workflow's stages and the report's name. A swarm's telemetry sidecar
+  (`<db>.telemetry.jsonl`, written by hypswarm) rides the same stream as `telemetry` events, so the Live view shows every
+  model and tool call as it happens.
 - **CI:** `hypgraph export -o record.bundle.json && hypgraph verify record.bundle.json`. The bundle is a single file
-  your reviewers or auditors can check with SHA-256, in any language or in the browser.
+  your reviewers or auditors can check with SHA-256, in any language or in the browser. `--telemetry` carries the
+  swarm's sidecar too, outside the chain, so the bundle replays the run with no server.
 
 The full guide is at [hypgraph.com/engineers](https://hypgraph.com/engineers/).
 
@@ -204,11 +212,13 @@ The full guide is at [hypgraph.com/engineers](https://hypgraph.com/engineers/).
 ```bash
 pip install hypgraph
 hypgraph demo        # a complete worked investigation (Broad Street, 1854) built into ./research.hypgraph
-hypgraph serve       # explore it in the Atlas: http://127.0.0.1:8765
+hypgraph serve       # explore it in the HypGraph UI: http://127.0.0.1:8765
 hypgraph report      # the facts, generated from the record
 ```
 
-Or try to get a claim past the real engine in your browser: [hypgraph.com/play](https://hypgraph.com/play/).
+Or watch a swarm work in each profile, replayed live from its record:
+[hypgraph.com/examples](https://hypgraph.com/examples/). Or try to get a claim past the real engine in your browser:
+[hypgraph.com/play](https://hypgraph.com/play/).
 
 ## Where it came from
 
@@ -219,7 +229,7 @@ egress, pulled out so anyone can use it. Each rule exists because the agents mad
 - a summary whose numbers matched no result;
 - "never" written about something that happened once in a thousand.
 
-PegasusDMZ is the reference deployment, and its Atlas is built from this package. Against PegasusDMZ's live record
+PegasusDMZ is the reference deployment, and its graph UI is built from this package. Against PegasusDMZ's live record
 (1,357 events, 790 nodes), the library derives the same standing for every node as the engine it replaced.
 
 ## Performance

{hypgraph-0.5.2 → hypgraph-0.6.0}/README.md

@@ -120,7 +120,8 @@ record behaves exactly as before.
 met, every gate MET / NOT MET with what would meet it); `GET /api/graph/stages`; MCP tool `stage`. A workflow
 widens what puts dependants AT RISK — `uses` (a corrected data file, a superseded diff or instance), `cites` (a
 withdrawn source) — and evidence goes **stale** when the artifact it used is superseded or its `valid_until` has
-passed. An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
+passed. A result whose run names no file it read goes stale when an input file of its question changes after it:
+nothing shows it read the new version (name the files with `uses` and only those count). An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
 verified failure each complete a question the gates alone never would.
 
 Profiles are versioned and frozen: a record written under `trading@1` means the same thing in a year, and the `@1`
@@ -161,9 +162,16 @@ with g.writing_for(task_id):                                # every event carrie
 - **Multi-agent:** give each agent its own author name. Make your critic agents reviewers. Have your job runner
   write as the instrument, so its runs count as recorded, not reported.
 - **Your web framework:** `hypgraph.server.dispatch(graph, method, path, query, body)` is the JSON API, and
-  `hypgraph.ui.static_dir()` is the Atlas explorer to mount next to it.
+  `hypgraph.ui.static_dir()` is the HypGraph UI to mount next to it.
+- **Watching it live:** `GET /api/graph/stream?inv=` pushes every event as it is written (Server-Sent Events,
+  resumable with `Last-Event-ID`), including writes from another process on the same file, such as a swarm running
+  against the record. `GET /api/graph/profile?inv=` gives the investigation's profile as a UI speaks it: each node
+  type's label ("Requirement", "Thesis"), the workflow's stages and the report's name. A swarm's telemetry sidecar
+  (`<db>.telemetry.jsonl`, written by hypswarm) rides the same stream as `telemetry` events, so the Live view shows every
+  model and tool call as it happens.
 - **CI:** `hypgraph export -o record.bundle.json && hypgraph verify record.bundle.json`. The bundle is a single file
-  your reviewers or auditors can check with SHA-256, in any language or in the browser.
+  your reviewers or auditors can check with SHA-256, in any language or in the browser. `--telemetry` carries the
+  swarm's sidecar too, outside the chain, so the bundle replays the run with no server.
 
 The full guide is at [hypgraph.com/engineers](https://hypgraph.com/engineers/).
 
@@ -172,11 +180,13 @@ The full guide is at [hypgraph.com/engineers](https://hypgraph.com/engineers/).
 ```bash
 pip install hypgraph
 hypgraph demo        # a complete worked investigation (Broad Street, 1854) built into ./research.hypgraph
-hypgraph serve       # explore it in the Atlas: http://127.0.0.1:8765
+hypgraph serve       # explore it in the HypGraph UI: http://127.0.0.1:8765
 hypgraph report      # the facts, generated from the record
 ```
 
-Or try to get a claim past the real engine in your browser: [hypgraph.com/play](https://hypgraph.com/play/).
+Or watch a swarm work in each profile, replayed live from its record:
+[hypgraph.com/examples](https://hypgraph.com/examples/). Or try to get a claim past the real engine in your browser:
+[hypgraph.com/play](https://hypgraph.com/play/).
 
 ## Where it came from
 
@@ -187,7 +197,7 @@ egress, pulled out so anyone can use it. Each rule exists because the agents mad
 - a summary whose numbers matched no result;
 - "never" written about something that happened once in a thousand.
 
-PegasusDMZ is the reference deployment, and its Atlas is built from this package. Against PegasusDMZ's live record
+PegasusDMZ is the reference deployment, and its graph UI is built from this package. Against PegasusDMZ's live record
 (1,357 events, 790 nodes), the library derives the same standing for every node as the engine it replaced.
 
 ## Performance

hypgraph-0.6.0/docs/ui-plan.md

@@ -0,0 +1,128 @@
+# HypGraph UI — plan (Atlas → HypGraph)
+
+*Status (2026-10-26): P1–P4 built and released in hypgraph 0.6.0; P5 (the Pegasus pod) waits for a rebuild. The
+decisions in §6 were taken as proposed: plain "HypGraph", light by default, OpenTelemetry as an optional extra with
+prompts and outputs off. The prototype the plan refers to (`dev/ui-prototype/`, with screenshots) lives on the
+proposal's branch, `ui-hypgraph` (PR #10), not on main.*
+
+## 1. Where it stands
+
+The explorer shipped as **Atlas** (`src/hypgraph/ui/atlas.js`, `hypgraph serve`, the site's `/atlas/`). It predates the
+profiles-as-workflows release (0.5) and was never updated for it:
+
+- **It knows only the scientific method.** Its six views (Graph, Hypotheses, Claims, Provenance, Work, Timeline) are
+  built around hypotheses and claims. Nothing in it reads a profile, a workflow, a stage or a gate. A software
+  record shows "hypotheses" where the team wrote designs; a trading record has no place for positions; a knowledge
+  record's sources and excerpts are just nodes.
+- **It has no notion of a running swarm.** It polls the record's events, so writes appear, but who holds which work
+  order, which model call is in flight, what it costs, and whether the run is stuck are not visible.
+- **It looks like a demo.** It has a dark neon theme, one dense canvas and a single investigation at a time.
+
+## 2. What it becomes
+
+**One product name: HypGraph.** "Atlas" goes everywhere: the page title, `hypgraph serve`'s banner, the site and the
+docs. For one release, `HypAtlas` stays as a global alias and `/atlas/` redirects, so embeds don't break.
+
+**It speaks each profile's language.** Every profile gains `labels`, a short noun per node type: a software
+`question` is a **Requirement**, a trading `hypothesis` is a **Thesis**, an optimization `result` is a **Solution**.
+Every view uses them, and the stages, gates and report name come from the profile's workflow. A record with no
+profile falls back to the kernel's words.
+
+**Information architecture.** These are the prototype's eight views, all driven by data the engine already derives:
+
+| view | what it answers |
+|---|---|
+| **Overview** | Is this done, and is it sound? KPI tiles (settled, checked, stale, contested, work orders, spend), the completion criteria, each question's stage, recent activity |
+| **Live** | What is the swarm doing right now? (§3) |
+| **Pipeline** | Where is each question in the workflow, and what would move it? A swimlane of the profile's stages with each gate MET / NOT MET, its evidence and what would meet it |
+| **Graph** | What rests on what? The graph, with profile labels, checked and stale rings, and click-through to the node |
+| **Evidence** | Every claim, result, source and decision, with its derived standing: checked, stale, contested, at risk, re-run by the instrument |
+| **Work orders** | What was each seat asked to do, its predicates for done, and how it ended |
+| **Audit log** | The append-only event log, with the hash chain re-verified on read (the badge in the top bar) |
+| **Report** | The profile's report (Change report, Desk note, Sourced brief, …), with PDF and bundle export |
+
+**Enterprise properties.**
+- **Look:** light theme first, with dark available. Dense, tabular and calm. One accent colour (the brand blue);
+  status colour only for status.
+- **Every screen is a URL:** `#view=pipeline&inv=software@2&q=Q1&at=40`.
+- **Trust is visible:** a "chain verified · N events" badge, derived standing everywhere, nothing settable by hand.
+- **Search:** ⌘K across nodes, questions and orders.
+- **Keyboard and accessibility:** keyboard navigation, WCAG-AA contrast in both themes.
+- **Export:** CSV for tables, PNG and JSON for the graph, PDF for the report, a verifiable bundle for the record.
+- **Read-only by default:** the UI never writes. Approvals and human review, when they come, go through the
+  record's own API with an author, like every other write.
+- **No build step, no network:** vanilla ES modules plus the vendored Cytoscape, served by `hypgraph serve` or
+  opened from a static site.
+- **The CLI is unchanged.**
+
+## 3. Live observability for a running swarm
+
+The goal is everything a run does, from start to end, visible as it happens and auditable afterwards.
+
+**Two streams, one timeline.**
+1. **The record** (truth): every write, review, refusal, lease, supersession and stage change. It is already
+   hash-chained. `hypgraph serve` gains `GET /api/graph/stream?inv=` (Server-Sent Events) so the UI is pushed each
+   event instead of polling.
+2. **Swarm telemetry** (observation, never trusted for standing): what the record can't see. HypSwarm emits
+   structured events:
+   - **Run:** start, stop, why it stopped, budget and its warning line.
+   - **Seats:** each seat's lifecycle, what it holds and what it is doing now.
+   - **Model calls:** model id, tokens in, cached and out, $, latency, retries, errors.
+   - **Tool calls:** name, a scrubbed summary of the arguments, duration, ok or error.
+   - **Scheduler decisions:** dispatch, rework, escalation, re-verification, refresh, world changes, and report
+     assembled or lost.
+
+   Each event carries `run_id`, `inv`, `seat`, `order`, `span_id` and `parent_span_id`.
+
+**Where telemetry goes** (`run(..., telemetry=…)`):
+- **JSONL sidecar** (default, local): `<record>.telemetry.jsonl`. `hypgraph serve` tails it and merges it into the
+  stream.
+- **OpenTelemetry** (optional extra `hypswarm[otel]`): traces as run → order → model call / tool call spans; metrics
+  for tokens, $, calls and latency per seat and model; logs for the rest. This feeds Datadog, Grafana, Honeycomb and
+  Splunk without any HypGraph-specific code.
+- **Scrubbing:** secrets and arguments are scrubbed before they leave the process. Prompts and outputs are off by
+  default and can be switched on per run.
+
+**The Live view.** The prototype shows its shape on replayed real event logs:
+- **Run header:** running / settled / stopped, elapsed time, events per minute, budget burn ($ and calls against
+  the cap, warning line), and play / pause / scrub for replay of finished runs.
+- **Seats:** each seat with its current work order and, with telemetry, its in-flight model or tool call (spinner,
+  model, elapsed), writes, cost and errors.
+- **The record, growing:** nodes appear as they're written, with stale rings appearing as files change.
+- **Event stream:** record and telemetry merged, filterable by seat, kind and order.
+- **Alerts:** a seat holding an order past its lease, the same tool failing repeatedly, a loop of identical calls,
+  the budget warning line, a refusal burst, stale evidence, a lost report.
+- **Trace:** a waterfall per work order: the order's span with each model and tool call inside, tokens and $ per
+  span, and where the time went.
+
+A finished run's Live view is the same screen fed from the record plus its telemetry sidecar, so every run can be
+replayed exactly.
+
+## 4. The site: a working example per profile
+
+Each `@2` profile gets an interactive page, `/examples/<profile>/`, running the new UI read-only on a real record.
+The records come from HypSwarm's five scripted examples: 01 scientific, 02 software, 03 trading, 04 knowledge,
+05 optimization. Each page opens on the **Live replay** of that run, so a visitor watches the swarm work, then can
+explore the Pipeline, Graph, Evidence and Report.
+
+This needs the bundle to carry what the UI shows. `derived` gains `profile` (labels, stages, report name), `stages`,
+`completion`, `board`, `orders` and the `report` markdown, plus the telemetry sidecar when one exists. As now, the
+bundle's hash chain is re-verified in the browser, and its derived views are shown as derived and never trusted.
+
+## 5. Phases
+
+| phase | what | verified by |
+|---|---|---|
+| **P0** | this plan and the prototype (real data, eight views, deep links, light and dark) | screenshots in `dev/ui-prototype/shots/` |
+| **P1 · engine** | `Profile.labels` for the five profiles; the bundle's `derived` gains profile, stages, completion, board, orders and report; `GET /api/graph/stream` (SSE); "Atlas" renamed in server, CLI and docs | tests; a bundle round-trip; `hypgraph serve` streaming a write |
+| **P2 · UI** | `src/hypgraph/ui/` rebuilt as the HypGraph app (ES modules, no build), all eight views, ⌘K, exports, accessibility; `HypAtlas` alias and `/atlas` redirect | headless screenshots of every view × profile × theme in CI; keyboard and contrast checks |
+| **P3 · telemetry** | HypSwarm's event schema, JSONL sink and optional OTLP exporter; serve merges telemetry into the stream; Live view on a real running swarm, with alerts and the trace waterfall | an end-to-end test: a scripted swarm against a served record, with the UI updating as it runs |
+| **P4 · site** | five profile example pages with Live replay; the site's Atlas page replaced; docs | the pages load offline from the bundle; the chain verifies in the browser |
+| **P5 · pod** | Pegasus's `/atlas` moves to the new UI (needs a pod rebuild: your go-ahead) | the pod's UI smoke check |
+
+## 6. Decisions (taken as proposed)
+
+1. **Name in the UI:** "HypGraph" as the plain product name (prototype), or a qualifier ("HypGraph Console" /
+   "HypGraph Explorer")?
+2. **Theme:** light by default for enterprise (prototype), with dark one click away?
+3. **Telemetry:** OpenTelemetry as an optional extra (proposed), and prompts/outputs off by default?

{hypgraph-0.5.2 → hypgraph-0.6.0}/src/hypgraph/__init__.py

@@ -16,7 +16,7 @@ Standing is derived on every read, never stored; every write is an event in a SH
 their numbers; reviews pin versions; independence is counted, not assumed. See https://hypgraph.com.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.6.0"
 
 from .bundle import verify_bundle  # noqa: E402
 from .graph import Author, Graph, GraphError, file_sha256  # noqa: E402

{hypgraph-0.5.2 → hypgraph-0.6.0}/src/hypgraph/bundle.py

@@ -11,17 +11,25 @@ SHA-256 over strings plus a few lookups — any language can do it (the site doe
      "versions": [{"node", "v", "at", "by", "reason", "body"}],   # body = the stored canonical string
      "edges":    [{"id", "src", "src_v", "rel", "dst", "dst_v", "data", "at", "by", "why"}],   # data likewise
      "withdrawals": [...], "retractions": [...], "leases": [...],
-     "derived":  {...}}                                     # standing at export time, for viewers; never trusted
+     "derived":  {...},                                     # standing at export time, for viewers; never trusted
+     "telemetry": {"source", "covered_by_chain": false, "events": [...]}}   # optional: a swarm's telemetry sidecar
 
 A scoped bundle (one investigation out of a shared graph) redacts the events outside it to {seq, hash, prev}: their
 content can't be checked, so a change hidden among them (a withdrawal, say) would not show. ``verify_bundle`` says so
 (``complete: false``). To publish a study, keep it in a graph of its own and export all of it.
+
+``export(..., telemetry=path)`` adds a swarm's telemetry sidecar (HypSwarm writes ``<record>.telemetry.jsonl``): its
+model and tool calls, work orders and scheduler decisions, so a viewer can replay the run. Telemetry is observation:
+it is not part of the hash chain, ``verify_bundle`` doesn't look at it, and nothing derived from the record rests on
+it. It is off unless asked for — a sidecar names the models, seats and spend of a run.
 """
 
 from __future__ import annotations
 
 import hashlib
 import json
+import os
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from . import __version__
@@ -37,7 +45,23 @@ def _sha(s: str) -> str:
     return hashlib.sha256(s.encode()).hexdigest()
 
 
-def export(g: "Graph", inv: str = "", *, derived: bool = True) -> dict:
+def read_sidecar(path: str | os.PathLike, invs: set[str] | None = None) -> list[dict]:
+    """Every complete JSON line of a telemetry sidecar; with ``invs``, those investigations' events (and any without
+    one). Lines that aren't JSON objects — a torn last line, say — are skipped."""
+    out: list[dict] = []
+    with open(path, "rb") as f:
+        for line in f.read().splitlines():
+            try:
+                e = json.loads(line)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                continue
+            if isinstance(e, dict) and (invs is None or e.get("inv") in (None, "") or e.get("inv") in invs):
+                out.append(e)
+    return out
+
+
+def export(g: "Graph", inv: str = "", *, derived: bool = True,
+           telemetry: str | os.PathLike | list | None = None) -> dict:
     with g._snap_lock:
         con = g._connect()
         rows = lambda q, *a: [dict(zip([c[0] for c in cur.description], r))  # noqa: E731
@@ -77,8 +101,15 @@ def export(g: "Graph", inv: str = "", *, derived: bool = True) -> dict:
         "events": events, "nodes": nodes, "versions": versions, "edges": edges,
         "withdrawals": withdrawals, "retractions": retractions, "leases": leases,
     }
+    invs = [inv] if inv else [n["id"] for n in nodes if n["type"] == "investigation"]
     if derived:
-        out["derived"] = derive_views(g, [inv] if inv else [n["id"] for n in nodes if n["type"] == "investigation"])
+        out["derived"] = derive_views(g, invs)
+    if telemetry is not None:
+        if isinstance(telemetry, (str, os.PathLike)):
+            src, tel = Path(telemetry).name, read_sidecar(telemetry, set(invs))
+        else:
+            src, tel = "", [e for e in telemetry if isinstance(e, dict) and e.get("inv") in (None, "", *invs)]
+        out["telemetry"] = {"source": src, "covered_by_chain": False, "events": tel}
     return out
 
 
@@ -91,9 +122,15 @@ def _event_in(kind: str, ref: str, p: dict, ids: set, eids: set) -> bool:
 def derive_views(g: "Graph", invs: list[str]) -> dict:
     """What a viewer needs without running the engine: standing of every node and the per-investigation views."""
     views = {"investigations": [i for i in g.investigations() if i["id"] in invs], "stats": g.stats(), "by_inv": {}}
+    from . import profiles
     for i in invs:
+        pid = str((g.get(i).get("body") or {}).get("profile") or "")
         views["by_inv"][i] = {"subgraph": g.subgraph(i), "work": g.work_map(i), "next": g.next_experiments(i, 20),
-                              "report": g.report(i)}
+                              "report": g.report(i),
+                              # the workflow views (hypgraph 0.6): a viewer shows each question's stage and gates,
+                              # the board, the work orders and the profile's own words without the engine
+                              "profile": profiles.view(pid), "stages": g.stages(i), "completion": g.completion(i),
+                              "board": g.question_board(i), "orders": g.orders(i)}
     views["verify"] = g.verify()
     return views
 

{hypgraph-0.5.2 → hypgraph-0.6.0}/src/hypgraph/cli.py

@@ -2,7 +2,7 @@
 hypgraph — the command line.
 
     hypgraph demo                       build the Broad Street (1854) teaching investigation into ./research.hypgraph
-    hypgraph serve                      open the Atlas explorer on http://127.0.0.1:8765
+    hypgraph serve                      open the HypGraph UI on http://127.0.0.1:8765
     hypgraph init "Plant growth" --objective "…" --reviewers ada,lin
     hypgraph add hypothesis statement="Blue light grows cress faster." predictions='["taller after 7 days"]'
     hypgraph add result summary="Blue trays averaged 41 mm, red 33 mm." values='{"blue_mm": {"value": 41}}'
@@ -291,13 +291,20 @@ def cmd_verify(args) -> int:
 def cmd_export(args) -> int:
     g = _graph(args)
     inv = g.resolve(args.inv) if args.inv else ""
-    b = g.export(inv)
+    tel = None
+    if args.telemetry:
+        tel = Path(g.path + ".telemetry.jsonl") if args.telemetry == "auto" else Path(args.telemetry)
+        if not tel.is_file():
+            print(f"no telemetry at {tel}", file=sys.stderr)
+            return 2
+    b = g.export(inv, telemetry=tel)
     data = json.dumps(b, ensure_ascii=False, separators=(",", ":") if args.compact else None,
                       indent=None if args.compact else 1)
     if args.output:
         Path(args.output).write_text(data, encoding="utf-8")
         print(f"Wrote {args.output}: {len(b['events'])} events, {len(b['nodes'])} nodes"
-              + ("" if b["complete"] else f" ({b['redacted_events']} events outside the investigation redacted)"))
+              + ("" if b["complete"] else f" ({b['redacted_events']} events outside the investigation redacted)")
+              + (f", {len(b['telemetry']['events'])} telemetry events" if tel else ""))
     else:
         print(data)
     return 0
@@ -418,7 +425,7 @@ def cmd_serve(args) -> int:
     if tokens and not args.writable:
         print("note: --token only matters with --writable (reads are open)")
     serve(args.db, host=args.host, port=args.port, writable=args.writable, open_browser=not args.no_browser,
-          tokens=tokens or None)
+          tokens=tokens or None, telemetry=(args.telemetry or "auto") if not args.no_telemetry else None)
     return 0
 
 
@@ -501,6 +508,9 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--inv", default="", help="one investigation (events outside it are redacted)")
     s.add_argument("-o", "--output", default="")
     s.add_argument("--compact", action="store_true")
+    s.add_argument("--telemetry", nargs="?", const="auto", default="", metavar="FILE",
+                   help="carry a swarm's telemetry sidecar for replay (default FILE: <db>.telemetry.jsonl); "
+                        "outside the hash chain")
     s = cmd("import", cmd_import, "rebuild a graph file from a complete bundle")
     s.add_argument("bundle")
     cmd("demo", cmd_demo, "build the Broad Street (1854) teaching investigation")
@@ -524,11 +534,14 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--install", action="store_true", help="write .claude/skills/hypgraph/SKILL.md")
     s.add_argument("--user", action="store_true", help="install under your home directory instead of this project")
     s.add_argument("--dir", default="", help="project directory to install into (default: here)")
-    s = cmd("serve", cmd_serve, "the Atlas explorer and JSON API on localhost")
+    s = cmd("serve", cmd_serve, "the HypGraph UI and JSON API on localhost")
     s.add_argument("--host", default="127.0.0.1")
     s.add_argument("--port", type=int, default=8765)
     s.add_argument("--writable", action="store_true", help="also accept writes (POST /api/graph/write)")
     s.add_argument("--no-browser", action="store_true")
+    s.add_argument("--telemetry", default="", metavar="FILE",
+                   help="a swarm's telemetry sidecar to stream (default: <db>.telemetry.jsonl, picked up when it appears)")
+    s.add_argument("--no-telemetry", action="store_true", help="don't serve or stream telemetry")
     s.add_argument("--token", action="append", metavar="SECRET[=AUTHORS]",
                    help="bind writes to a bearer token: SECRET=a,b (those authors) or SECRET=* (any non-reserved); "
                         "repeatable; $HYPGRAPH_TOKEN adds one. With tokens, unauthenticated writes are 401.")

{hypgraph-0.5.2 → hypgraph-0.6.0}/src/hypgraph/derive.py

@@ -146,6 +146,14 @@ def risky(s: Snap, x: str) -> tuple:
     return RISKY + extra if extra else RISKY
 
 
+def workflow_profile(s: Snap, x: str) -> bool:
+    """Whether x's investigation runs a profile with a workflow (the @2 profiles): freshness rules that need the files
+    to be registered apply only there."""
+    inv = s.nodes.get(s.nodes[x]["inv"]) if x in s.nodes else None
+    pid = str((inv or {}).get("body", {}).get("profile") or "").lower()
+    return bool(pid) and pid in EXTRA_RISKY
+
+
 def upstream(s: Snap, x: str) -> list[tuple[str, str]]:
     """What x rests on, one step: premises (requires), derivations, a decision's basis, and the run that produced it.
     Support is counted separately (unsupported): one fallen support among several doesn't break a claim."""
@@ -169,10 +177,68 @@ def excerpts(s: Snap, sid: str) -> list[str]:
             and s.nodes[e["src"]]["type"] == "artifact" and (s.nodes[e["src"]]["body"].get("kind") or "") == "excerpt"]
 
 
+def _order(s: Snap) -> tuple[dict, dict, dict]:
+    """When each node was created, each edge linked and each node withdrawn, as event sequence numbers (timestamps
+    are only to the second). Cached on the snapshot until the next event."""
+    cached = getattr(s, "_order_cache", None)
+    if cached and cached[0] == s.seq:
+        return cached[1]
+    made: dict[str, int] = {}
+    linked: dict[int, int] = {}
+    gone: dict[str, int] = {}
+    for e in s.events:
+        if e["kind"] == "create":
+            made.setdefault(e["ref"], e["seq"])
+        elif e["kind"] == "link" and isinstance(e.get("payload"), dict) and e["payload"].get("edge") is not None:
+            linked[int(e["payload"]["edge"])] = e["seq"]
+        elif e["kind"] == "withdraw":
+            gone.setdefault(e["ref"], e["seq"])
+    out = (made, linked, gone)
+    s._order_cache = (s.seq, out)                      # type: ignore[attr-defined]
+    return out
+
+
+def _moved_since(s: Snap, rid: str) -> list[str]:
+    """Input files of the result's investigation that were replaced or withdrawn after the result was written. A run
+    output (an artifact some run produced) and a page excerpt (a re-fetch supersedes it every time) don't count, and a
+    file registered on other questions only (``part_of``) doesn't count against a result on a different one."""
+    from .workflow import question_of                  # workflow imports derive; read lazily
+    made, linked, gone = _order(s)
+    t = made.get(rid)
+    if t is None:
+        return []
+    inv = s.nodes[rid]["inv"]
+    q: set | None = None
+    out = []
+    for aid, a in s.nodes.items():
+        if a["type"] != "artifact" or a["inv"] != inv or (a["body"].get("kind") or "") == "excerpt":
+            continue
+        if any(e["rel"] == "produced" for e in s.inn.get(aid, [])):
+            continue
+        on = {e["dst"] for e in s.out.get(aid, []) if e["rel"] == "part_of" and s.nodes[e["dst"]]["type"] == "question"}
+        if on:
+            if q is None:
+                # a result reaches its question through the claims built on it, as often as through its run
+                qs = {question_of(s, rid)} | {question_of(s, e["src"]) for e in s.inn.get(rid, [])
+                                               if e["rel"] == "derived_from"}
+                qs |= {question_of(s, e["dst"]) for e in s.out.get(rid, []) if e["rel"] == "supports"}
+                q = {x for x in qs if x}
+            if q and not (q & on):
+                continue
+        when = [linked.get(e["id"], 0) for e in s.inn.get(aid, []) if e["rel"] == "supersedes"]
+        if aid in gone:
+            when.append(gone[aid])
+        if any(w > t for w in when):
+            out.append(a["code"] or aid)
+    return out
+
+
 def stale(s: Snap, nid: str) -> list[str]:
     """Why a result (or a claim through its results) no longer speaks for what it measured; [] when fresh. A result
     is stale when the run that produced it used an artifact that is now superseded or withdrawn, or when its
-    ``valid_until`` has passed. A source is stale when the host re-fetched its page and the page as it is now no
+    ``valid_until`` has passed. Under a workflow, a result whose run names no file it read (no ``uses``) is stale once
+    any input file of its investigation is replaced or withdrawn after it was written: nothing shows it read the
+    new one. A source is stale when the host re-fetched its page and the page as it is now no
     longer contains its passage (the live excerpt says ``contains_passage: false``), or every excerpt of it was
     superseded. A claim is stale when it has results or cited sources and every one of them is stale."""
     n = s.nodes[nid]
@@ -200,6 +266,11 @@ def stale(s: Snap, nid: str) -> list[str]:
                 a = s.nodes[e["dst"]]
                 kind = a["body"].get("kind") or "artifact"
                 out.append(f"{kind} {a['code'] or e['dst']} is {lc}")
+        named = run and any(e["rel"] == "uses" for e in s.out.get(run, []))
+        if not named and workflow_profile(s, nid):
+            moved = _moved_since(s, nid)
+            if moved:
+                out.append(f"it names no file it read, and {', '.join(moved[:3])} changed after it was written")
         vu = str(n["body"].get("valid_until") or "").strip()
         if vu and s.now and s.now[:len(vu)] > vu:
             out.append(f"valid_until {vu} has passed")
@@ -469,6 +540,15 @@ def affected_by(s: Snap, touched: set) -> set:
     invs = {x for x in stack if s.nodes[x]["type"] == "investigation"}
     if invs:
         stack += [i for i, n in s.nodes.items() if n["inv"] in invs]
+    # a changed file reaches the results that name no file through no edge (see stale): under a workflow, every such
+    # result in the file's investigation may have gone stale
+    moved = {s.nodes[x]["inv"] for x in stack if s.nodes[x]["type"] == "artifact"}
+    if moved:
+        for i, n in s.nodes.items():
+            if n["type"] == "result" and n["inv"] in moved and workflow_profile(s, i):
+                run = producing_run(s, i)
+                if not (run and any(e["rel"] == "uses" for e in s.out.get(run, []))):
+                    stack.append(i)
     while stack:
         y = stack.pop()
         if y in out: