The README's first code block contain some LangGraph's API, not GraphARC's - #55
Merged
Merged
Conversation
Every call in the Quick Start was wrong, and it was the first code a visitor
copies. Verified against this tree rather than read:
- `from grapharc.runtime import StateGraph` -> ImportError. This package has
never exported `StateGraph`; the module exports `GraphARC`. The very first
line failed, so nobody who pasted the block got as far as the rest.
- `add_node("process", lambda ...)` with no `writes=` -> TypeError, the
argument is required. Per-node write permissions are the project's headline
claim, and the snippet showed them being skipped.
- `add_edge("START", "process")` -> ValueError: unknown node 'START'. START is
a sentinel, not the string.
- Plain `pydantic.BaseModel` for state. Accepted at runtime, but it sidesteps
`GraphARCState` and the typed-contract story the page is selling.
The block came in with 241b272 ("README refactoring: improve discoverability
and structure"), which also added a contents list whose `#usage` and
`#documentation` entries point at sections that do not exist — a dead anchor
on GitHub silently does nothing when clicked, so reading the page never
surfaced it either.
Replaced with a snippet that runs, and that shows the three things that are
actually the point: typed state, declared writes, a Budget on the run. The
contents list now names the real sections.
Nothing caught any of this because nothing ran it. This module's own docstring
describes exactly that drift for the admission-gate section and fixes it by
executing the block; the Quick Start had the same standing on the page and
none of the discipline. So it gets the same treatment:
- `test_the_quick_start_block_actually_runs_against_this_tree` executes the
block and compares stdout with the result the page states.
- `test_the_quick_start_reaches_no_live_backend` keeps the first snippet a
visitor copies from being able to spend money.
- `test_every_table_of_contents_link_resolves_to_a_real_heading` derives
anchors the way GitHub does and fails on a dead one.
Both new tests were confirmed to fail against the old README and pass against
the new one, so they are not vacuous. Full suite green on 3.12; ruff clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every call in the Quick Start was wrong, and it was the first code a visitor copies. Verified against this tree rather than read:
from grapharc.runtime import StateGraph-> ImportError. This package has never exportedStateGraph; the module exportsGraphARC. The very first line failed, so nobody who pasted the block got as far as the rest.add_node("process", lambda ...)with nowrites=-> TypeError, the argument is required. Per-node write permissions are the project's headline claim, and the snippet showed them being skipped.add_edge("START", "process")-> ValueError: unknown node 'START'. START is a sentinel, not the string.pydantic.BaseModelfor state. Accepted at runtime, but it sidestepsGraphARCStateand the typed-contract story the page is selling.The block came in with 241b272 ("README refactoring: improve discoverability and structure"), which also added a contents list whose
#usageand#documentationentries point at sections that do not exist — a dead anchor on GitHub silently does nothing when clicked, so reading the page never surfaced it either.Replaced with a snippet that runs, and that shows the three things that are actually the point: typed state, declared writes, a Budget on the run. The contents list now names the real sections.
Nothing caught any of this because nothing ran it. This module's own docstring describes exactly that drift for the admission-gate section and fixes it by executing the block; the Quick Start had the same standing on the page and none of the discipline. So it gets the same treatment:
test_the_quick_start_block_actually_runs_against_this_treeexecutes the block and compares stdout with the result the page states.test_the_quick_start_reaches_no_live_backendkeeps the first snippet a visitor copies from being able to spend money.test_every_table_of_contents_link_resolves_to_a_real_headingderives anchors the way GitHub does and fails on a dead one.Both new tests were confirmed to fail against the old README and pass against the new one, so they are not vacuous. Full suite green on 3.12; ruff clean.