graphs.sgit.ai → the second edition → The methods
The methods register
Part of what the book talks about is how it was made. Every technique here was used in earnest on this project before being written down, each names the release where it first shipped, and superseded techniques stay listed with their supersession recorded, because the register obeys the discipline it documents.
Why this is book material and not housekeeping. The second edition argues that conclusions about a body of work should be computed, that history should be part of the graph, and that a rule with no enforcement is a preference. Every row below is one of those arguments having actually been lived, with the release where it first shipped and the code that enforces it. The method chapter of the second edition is written from this register.
| Technique | What it is | Born | Lives in | For the book |
|---|---|---|---|---|
| The projection chain with gates | Content lives in one source form and every published surface is generated from it, with a validator that fails the build on drift between them. A page cannot disagree with its source because the page is not authored. | v0.1.0 | admin/build/validate.jsadmin/build/chrome.py | The mechanism behind 'computed conclusions rather than asserted ones' applied to publishing itself. |
| Validate, tag, deploy on every push | Every push to the deploy branch is a release: gates run, a version is tagged, the site ships. A release costs one commit, so corrections ship the moment they exist. | v0.1.0 | .github/workflows | Why the history has forty releases in days: cheap releases make the record fine-grained enough to learn from. |
| The book as a projection of the site | Chapters, a single page, print and screen PDFs and a computed cover, all generated from the same sources as the site pages, gated so neither can drift from the other. | v0.2.0 | admin/build/gen_book.pyadmin/build/gen_cover.py | One source, many compressions: the fractal claim as a build pipeline. |
| The review workflow as a typed register | Reviews are JSON items with states (applied, discussing, declined), threaded answers, and pages projected from the register, so review history is queryable rather than buried in chat. | v0.3.8 | assets/review.js | Disagreement made visible and specific, which is the method's whole claim. |
| Decisions as peaks of a graph | Each open decision is the top of a graph linking its question, options, side effects and the work it blocks; the founder's answers are captured beside it. The whole-register view found blocked work that two decisions each were waiting on under different names. | v0.3.13 | admin/build/gen_decisions.pyassets/decisions.js | An aggregate view producing a finding no per-item view could. |
| Carried sources: byte copies with hashes | Source documents are carried whole, byte for byte, each with its SHA-256 recorded and re-verified, so a citation is to bytes that provably have not moved. | v0.3.24 | admin/build/gen_docs.py | The provenance chain applied to the book's own inputs. |
| Three kinds of link, drawn apart | Carried (byte copy plus hash), measured (computed from published phrase lists, drawn dashed with a count), authored (a decision with a note, drawn solid). A reader can always tell which trust a line carries. | v0.3.24 | assets/docs.js | Evidence states as a visual grammar. |
| Computed peaks and concentration | A concept's strength and a corpus's peaks are computed from edges, units and demonstrations by a published formula that can be argued with; concentration separates a concept the corpus distributes from one that two documents carry. | v0.3.20 | admin/build/gen_altitudes.pyadmin/build/gen_docs.py | Themes are computed, not declared: ADR-4's ancestor. |
| The altitude ladder | One book at five altitudes, each complete at its own altitude, related by compression running upward. The pilot proved the method the second edition is built on. | v0.3.15 | admin/build/gen_altitudes.py | The second book's own table of contents, piloted on the first. |
| Supersede, never delete | Corrections are printed beside the originals: amendments name the decision they amend, superseded definitions stay visible under their replacement, and the build fails on an amendment naming nothing. | v0.4.2 | decisions/amendments.jsonadmin/build/gen_decisions.py | History as part of the graph rather than something a correction erases. |
| The edition freeze: move, manifest, hash gate | A finished edition moves under its own prefix, every byte is recorded in a manifest, and the build fails if any of them changes. Verified negatively before being declared done: change one byte, watch the build fail, put it back. | v0.4.0 | admin/build/gen_freeze.pyadmin/build/validate.js | What makes anchors into history stable forever. |
| Redirect stubs at former addresses superseded at v0.4.7 | Every page that moved kept a generated stub at its old address, pointing at the new one. Cheap insurance while the estate had possible external readers of the old paths. Retired at v0.4.7 on the founder's call: the estate confirmed no external users of the old paths, and 108 stubs were more repo complexity than insurance. The generator went with them; git history holds both. | v0.4.0 | admin/build/gen_redirects.py | A compatibility layer is a cost worn knowingly, and retired knowingly. |
| Review packs: documents that control the sequence | One continuous page and a PDF printed from it, read end to end with no link followed, stamped with the SHA-256 of every data file it drew from, gated stale. A reviewer answers the pack, not the site. | v0.4.3 | admin/build/gen_packs.pyassets/pack.css | Sequence control as the reviewing counterpart of hyperlinks. |
| Figures captured from the live pages | A figure in a document is a Chromium screenshot of the published page it describes, so the figure is what a reader would see, and a missing figure is a stated absence rather than a blank. | v0.4.3 | admin/build/gen_pack_figures.py | Named absence applied to illustrations. |
| Each edition owns everything it uses | Everything about making an edition lives inside its tree, taken as copies with provenance blocks; anything outside the edition trees must be deletable without either edition losing content. /book/ is a pointer to the current edition, never a shelf. | v0.4.4 | v2/README.md | The decoupling of editions arriving as a property of the directory layout. |
| Quote-anchored extraction with a coverage rule | Every extracted node carries a verbatim quote at recorded byte offsets in a frozen source; the build fails if the quote is not at its bytes, and every section with prose either yields nodes or is recorded empty with a reason. | v0.4.5 | admin/build/gen_universe.pyadmin/build/validate.js | Extraction hallucination made build-detectable; silence made impossible. |
| One extraction, projected views | The dictionary, taxonomy, thesaurus and ontology of a document are projections of one extraction file, never four authored artefacts, so they cannot disagree with each other. | v0.4.5 | admin/build/gen_universe.py | The cure for the glossary-versus-concept-layer duplication the first edition carried. |
| The scoped lexicon with overrides | Multiple lexicons at different altitudes: the book's root scope, a scope per source document, later a scope per altitude. A scope may extend, specialise or override an inherited definition, with the authority recorded and the superseded definition kept visible. | v0.4.6 | admin/build/gen_lexicon.pyv2/lexicon/scopes | Fractal semantic graphs demonstrated on the book's own vocabulary. |
| The artefact catalogue | Point-in-time artefacts, the pages and PDFs that captured a particular moment with a particular set of sources and thinking, are preserved byte for byte in a catalogued area, hash-gated so they can never be silently overwritten. | v0.4.6 | admin/build/gen_artefacts.pyv2/artefacts | The history of how the result was reached is part of the result's graph. |
| The number nothing was checking | The recurring failure class: a count or date written into prose that no gate covers, drifting silently. Each instance found became a gate; the standing answer is that prose does not quote computed numbers. | v0.3.23 | admin/build/validate.js | The single most repeated lesson of the whole run, and gate 21 of the dev pack. |
| The anchored reader: source, extraction and graph on one screen | A per-document universe page gains a resizable side panel holding the local graph and the rendered frozen source. Anchor highlights are driven by the same byte offsets gate 23 verifies, never by re-searching the text: the raw bytes are sliced at the recorded offsets before rendering, so a highlight can only sit on the exact bytes the extraction cited. Clicking an extraction row shows the cited bytes; clicking a highlight shows the extraction row; clicking a graph node shows both; a toggle shows every anchor at once, which makes the coverage rule visible on the document itself. Since v0.4.13 the implementation is a three-tier ESM structure: a pure, node-tested core (segments, markup, doc tree, styles), custom elements that render and emit, and a thin reader shell; the unit suite is a build gate. | v0.4.8 | assets/universe-view.jsassets/universeassets/universe.cssadmin/build/gen_universe.py | The verified anchor is the interface: trust built at extraction time becomes navigation at reading time, at no new cost. |
| The standalone document folder, and the usage ledger | Everything the estate holds about one source document lives in one portable folder: a build-verified byte copy of the frozen source, the anchored extraction, and crossrefs.json, the ledger of where the document is used, each use rated against a published maturity model (aligned, stretched, misaligned, unrated) with the judgement signed and dated. The rating judges the use, never the user, and a superseded use keeps its rating with the supersession recorded. The first entry the model caught: the first edition's fractal definition, a stretched use of the cornerstone source, corrected at v0.4.6. | v0.4.10 | admin/build/gen_universe.pyv2/universe/usage-model.jsonv2/universe/docs | A document that captures where it is used can rate that use: the core of an author's ability to police the life of their ideas. |
| Node packs, and a peak for every family | The graph's contents are chosen as sources of nodes, not as one fixed view: the extraction's families, the document tree, the synthetic family peaks and the derived weaker links are each a pack, toggled in or out, and the view is their union. Every family gets a peak: a synthetic summit node (the dictionary, the claims, the hypotheses) with containment edges to its members, so the tree layout reads as pyramids, the document's own beside one per family. The first weaker-link layer is derived, never asserted: two concepts co-claimed by the same claim are joined by a dashed, counted, arrowless edge, drawn as measurement, not as a verb. One kinds list in the core tier drives the source pane's highlights and the graph's families from the same toggles, so the two panes cannot disagree about what is shown. | v0.4.14 | assets/universe/core/packs.jsassets/universe/core/kinds.jsassets/universe/components/uni-graph.js | The book's universe is packs of packs: each document contributes its families, each altitude gets its peak, and a reader composes the view instead of inheriting it. |
| Explore by degrees: focus, grow, and price the next hop | The answer to the dot-blob problem every graph database visualisation hits as edges multiply. From a selected node, the focused view shows exactly the selection at degree zero and grows one undirected ring at a time towards the peaks, with 'max' removing the limit. A stats bar counts what the current view holds, node families and edge kinds apart, and also prices the next hop: the families and edges one more degree would bring in, read before paying for it. Paths-to-peaks gold-lines the shortest routes from the selection to every visible summit. Five preset views (overview, reading map, pyramids, concept web, around selection) apply a whole preference bundle in one click and are plain data, so new common paths cost an entry, not code. | v0.4.14 | assets/universe/core/explore.jsassets/universe/core/views.jsassets/universe/components/graph-strip.js | When document graphs connect to the book's own universe the paths become massive; choosing a path by its price is how navigation survives the scale. |
| The document of one node | Brief 24's experiment, programmatic phase: pick one node and read the document that grows from it. The page assembles only what the anchored data verifiably holds — the node's definition quote at its recorded bytes, the claims about it, its directional relationships each with its own verb, the examples demonstrating it, its aliases and its explicit not-this distinctions, its derived weaker links, its rated uses across the estate, and a degrees table measuring how far it reaches. No prose is authored; the connecting prose is the later, LLM phase, running the book workflow from a single node upward. The picker ranks every node by its link count, so the richness of each concept is measurable before any writing happens: a rich node makes pages, a thin one makes a paragraph, and the difference is a finding. | v0.4.15 | assets/universe/core/nodedoc.jsassets/universe/nodedoc-page.jsadmin/build/gen_universe.py | The whole book is this operation on steroids: every altitude is a document grown from nodes, and the per-node page is the small end of the same telescope. |
| Pinned nodes (locked summits, free field) | Fix a small set of structurally important nodes on the canvas and let the force layout settle everything else around them. In the reader: doc root and family peaks stack the left edge, derived-group summits the right, locked only while a layout runs so they stay hand-draggable between runs; a re-triggered layout respects the dragged spots. Position becomes information (a free node's resting place is the visible sum of the forces on it), the map stays stable across re-layouts, starved families read as visibly under-tethered peaks, and every document's graph shares one spatial grammar. The full debrief of the technique and the problems it solves is at v2/dev-packs/v0.4.16__pinned-nodes/00__debrief.md. | v0.4.16 | assets/universe/core/packs.jsassets/universe/components/graph-fx.jsassets/universe/components/uni-graph.jsv2/dev-packs/v0.4.16__pinned-nodes/00__debrief.md | The chapter-level demonstration that a graph becomes a map only when it has landmarks: spend a few nodes' freedom to buy meaning for every other node's position. |
| Position-stable graph updates (stable add) | Brief 26's stability principle as a mode, on by default: every node move costs the reader their mental picture, so when the view gains or loses elements, what was on canvas holds still. Removals move nothing; additions freeze every previously shown node, seed each newcomer beside an already-placed neighbour, settle only the newcomers in the force field, then unlock. The viewport holds too: no layout is allowed to re-fit unless the reader explicitly asked for a new arrangement. Explicit asks (a layout button, the physics sliders, a preset) still lay out everything, because asking is not a context switch. | v0.4.28 | assets/universe/components/graph-fx.jsassets/universe/components/uni-graph.jsassets/universe/core/cystyle.js | The navigation claim made mechanical: a graph is explorable only while its map survives interaction, for a person and for an agent reading a snapshot alike. |
| The four areas, their slots, and the peak board | The border of the canvas divided into four rectangles (top, right, bottom, left), each with six aligned slots; the pinned summits live in slots, so the fixed nodes read as an aligned frame rather than a scatter. A dedicated board shows only the peaks, colour-coded by summit type, and the founder drags one from left to right or top to bottom; every change re-anchors the whole graph immediately and persists per document. The slot geometry is a pure, tested function; the board is an add-on part that edits assignments and hands them to the one layout pipeline. | v0.4.28 | assets/universe/core/slots.jsassets/universe/components/pin-board.jsassets/universe/components/graph-fx.js | Landmarks are authored, not computed: the human places the few anchors that give the canvas a geography, and the machine settles the many free nodes between them. |
| The schema view | A visualisation of just the schema: one node per node type with its member count, one edge per typed relation labelled with its verb (never the bare kind when a verb exists) and how often it occurs, shown exclusively on the same canvas with the same instrument. Brief 26 names its purpose: a great way to understand how good we are and what refactors we need. Day one on the pilot it shows claims reaching concepts through one relation used forty times while concept-to-concept runs through seven verbs used once or twice each, which is exactly the raw material for the one-direction-per-relation decision. | v0.4.28 | assets/universe/core/schema.jsassets/universe/components/uni-graph.js | A graph's quality is legible at the type level before it is legible anywhere else; the schema is the graph's own review pack. |
| The path query (trail, board, runner) | Brief 28's central move: navigating a graph hop by hop IS writing a query, so the trail a reader walks is recorded (node, verb, node), edited on a board (steps as chips: remove, reorder by drag, generalise a node to its family), and run by a pure tested engine that resolves displayed inverse verbs back to their stored direction through the verbs register. Run lights every matched path on the canvas; project-forward lists the verbs that could extend the path and appends one speculatively, showing what the future path would match before it is walked. Named queries persist per document. | v0.4.34 | assets/universe/core/pathquery.jsassets/universe/components/trail-board.jsassets/universe/components/graph-inspect.js | Queries are not written, they are walked: the reader's own navigation is the query language, and generalising one step at a time is how a single observation becomes a reusable question. |
| The immediate-connection register | A standing design document that names the experience target for every interactive surface in this repo: Bret Victor's principle that creators need an immediate connection to what they create, composed with the project's own stability rule that every unasked-for node move costs the viewer their mental picture. The register maps Victor's five demo patterns (scrub a value, show the future, show the data, behaviour on the thing, perform rather than configure) to the viewer features that already implement them, names the gaps, fully specifies two buildable ones (view time travel, relayout ghosts), and ends in a six-point checklist (immediate, stable, visible, projectable, direct, modular) that any change to an interactive surface should pass. It is written for agents: read it before building, update it when a pattern lands. | v0.4.35 | v2/dev-packs/design__immediate-connection/00__the-victor-register.md | Design taste can be captured as an executable register: when the target experience is written down as patterns plus a checklist, every future contributor (human or agent) extends the instinct on purpose instead of by luck. |
| The core graph: document to word | Brief 29's foundational move: the document transformed into a graph at every level of its own structure — document, section, block (paragraph, bullet item, code, quote, table), sentence, word — each level a node with an ID linked to its parent, like an AST driven by the content. Inline markup becomes span nodes covering the word instances they mark, and every distinct word gets a form node carrying its count and every instance, so emphasis and repetition are queryable structure. IDs are the reference currency at every level; byte ranges are kept only as build-time verification metadata, because pointing at character offsets breaks the moment the document changes. Storage answers the one-big-file question with shards: an index with the section skeleton, one shard per section fetched only when a viewer expands it, and the word-form index. Brief 30 added the two-way transform: formatting lives in its own graph (fmt.json — heading lines, gaps, raw markdown per block, joined to the semantic graph by the block IDs), and the build now rebuilds the source markdown from the graph and fails unless it is byte-identical, with a second gate proving the semantic shards re-derive from the formatting graph alone. Six gates in all: block ranges reassemble each section, sentences reassemble each block, form totals equal instance totals, spans cover the words they claim, the rebuild is byte-identical, and the two graphs cannot disagree. | v0.4.37 | admin/build/gen_coregraph.pyassets/universe/core/coretree.jsassets/universe/components/core-tree.js | Before a graph can carry meaning about a document it must first BE the document: a lossless, ID-addressed transform of every structural level, so that everything built above it points at stable identities instead of fragile offsets. |
| The document as its own token universe | Brief 30's move, inspired by how transformers tokenise but inverted: an LLM tokeniser caps the vocabulary to limit the universe, while a document needs no cap, so every word form is a token with full identity. The analysis pass classifies each form (padding, verb, content, code, number) with the meaning-density statistics on top (the pilot: 45% of word use is padding, 505 forms appear once), groups forms into stem families, surfaces near-miss pairs by edit distance, builds the co-occurrence graph over sentences (each form's centre of gravity, the document's own attention map), and scores every frequent content form for context spread, where a high count with diverse sentence neighbourhoods flags a candidate for different meanings in the same document. On the pilot the top candidates are 'node' and 'graph', the founder's own examples. All heuristic and statistical, no NLP model; recorded as such so a proper tagging pass can replace parts honestly. | v0.4.38 | admin/build/gen_coregraph.pyassets/universe/core/coretree.jsassets/universe/components/core-tree.js | A document read as its own token universe measures itself: how much of it is padding, where its meaning concentrates, which of its words secretly name more than one thing. The statistics are not the understanding, but they say exactly where understanding should look first. |
| The identity ledger (match-then-mint) | The answer to the founder's IDs question, with the load-bearing insight that randomness was never the missing ingredient — persistence was. Every document keeps a committed ledger (ids.json) mapping short opaque uids (tig:b42) to the current structural locator plus a content hash. The generator carries identities forward on every rebuild: same locator claims its uid first (edits in place just update the hash), then same content hash (a moved block's identity follows it), then fuzzy similarity of locator and text head (renamed and edited); only what matches nothing gets a freshly minted uid, and whatever the document no longer has is retired, never deleted, so identity history survives and uids are never reused. Cross-references hold the uid; the locator stays human-readable and free to move. Gate 7 makes the contract executable: full coverage, unique uids, and a second carry-forward pass over the ledger's own output must change nothing. Verified against the full edit repertoire: rename, edit in place, move, add, delete. | v0.4.40 | admin/build/gen_coregraph.pyv2/universe/docs/thinking-in-graphs/ids.json | Identity through change is the property offsets and paths can never give: mint an identity once, persist it, and make every rebuild prove it can carry the past forward before it is allowed to ship. The ledger diff between two versions is change detection for free: untouched, edited, moved, new, retired. |
| The WCLM: a deterministic transformer experiment | Brief 31's experiment, the founder's coinage: not a large language model but a words content language model. An engine in the shape of a transformer where nothing is learned and everything is named: tokens are content hashes (FNV-1a 64, the same word tokenises identically in every document, python and javascript implementations gate-checked against shared vectors), and six layers are pure functions with declared roles — tokenise, resolve, attend, bind, expand, converge. Attention is the co-occurrence and concept-binding the estate already computed, drawn as weighted arcs between layer columns. The query flips from predict-the-next-word to what-does-this-mean: the answer is a concept with its statement, anchored quote, blast radius and the visible path that produced it — an attribution graph by construction, where interpretability research must reverse-engineer one. Every weight is a stated formula written in the world file (class weight over log2(2+count); bind = half label coverage plus half prompt coverage; total = 2·bind + 0.1·blast): training this model is editing graph inputs and meaning packs, never fitting numbers. Meaning packs supply the world above the document (QA part-of development, issues-fs kind-of a version file system), authored extraction-style. | v0.5.2 | assets/wclm/engine.jsadmin/build/gen_wclm.pyv2/wclm/packs/graphs-domain.json | The transformer's shape survives with its mystery removed: when the layers are named transformations over graphs instead of learned matrices, the model's every answer arrives with its reasons attached, and training becomes editing meaning rather than fitting numbers. |
For an agent
The machine surface is data/methods.json. Each entry names the release it first shipped in (checkable against the release history) and the files that implement it (checked by the build for entries still in use). A superseded entry stays in the register with its supersession recorded; treat its presence as history, not as current practice.