graphmark 0.5.0__tar.gz → 0.7.0__tar.gz

{graphmark-0.5.0 → graphmark-0.7.0}/CHANGELOG.md

@@ -1,6 +1,251 @@
 # CHANGELOG
 
 
+## v0.7.0 (2026-07-25)
+
+### Documentation
+
+- Record the nine-vault corpus study ([#134](https://github.com/cdcoonce/graphmark/pull/134),
+  [`7495934`](https://github.com/cdcoonce/graphmark/commit/749593468e3d57913d89fc00942179786f5f5128))
+
+graphmark has had exactly one real vault, and a coverage run showed the problem is worse than n=1:
+  that vault now has zero broken links, so it never executes the error handling at all —
+  suggest_notes entirely, the ambiguous / missing / out-of-scope verdicts, unresolved recording, and
+  diagnose(). 54% of the package is unexercised by it. The healthier it gets, the less it validates.
+
+Nine third-party vaults, zero crashes — the first evidence for the README's 'any Obsidian-family
+  vault' claim. kepano's vault is 74% .base links, which independently justifies #101 and shows the
+  reference vault understated that class by 7x. Third-party vaults sit at 1.8-27% missing against
+  the reference vault's 0%.
+
+That range confirms #127's closure against real data rather than argument: the largest
+  false-positive class this package has had moved missing by 0.4%, which no threshold can separate
+  from ordinary variation.
+
+No new defects. Two suspicious distributions were both graphmark being right, and the second was my
+  own scoping error — I excluded English template directory names but not the Spanish 'Plantillas',
+  which is the methodological lesson worth recording for anyone repeating this.
+
+- **roadmap**: Close Track E, open Track F — auditable link accounting
+  ([#128](https://github.com/cdcoonce/graphmark/pull/128),
+  [`4ca84de`](https://github.com/cdcoonce/graphmark/commit/4ca84de110dd288cd2778ccdc48a3b558367b269))
+
+* docs(roadmap): close Track E, open Track F — auditable link accounting (#124-#127)
+
+afk-driver --expand reads this file verbatim, so it has to describe where the work actually is.
+  Track E is closed at 0.6.0 (aliases were its last piece), and the baseline line still claimed
+  0.3.4.
+
+Track F names the real problem, which is not any individual bug but how bugs get found: all seven
+  correctness defects in this package's history came from a human reading link lists on the single
+  reference vault, six of them in one day. The frozen oracle is a ratchet, not a detector — it has
+  never surfaced anything new — and the one consumer's seam actively conceals package defects,
+  having hidden a 23-link alias error for six releases.
+
+The mechanism of the hiding is that the buckets are silent: build sorts every display into one of
+  six reasons and reports one of them, and six of the seven bugs were mis-bucketing. Printing the
+  distribution would have made the alias gap obvious at a glance — zero alias-resolved beside 23
+  unresolved is visibly wrong.
+
+So the epic is to make the package's own answers auditable: every display in exactly one named
+  bucket, counted, reported, and bound by a property-tested conservation law. Sliced #124-#127, with
+  the detector (#126) as the point of the exercise and its catch rate as the evidence.
+
+Records what is deliberately deferred behind it and why: the Track D GitHub Action is an adoption
+  play this repo has already decided against, and shipping a gate that fails other people's builds
+  while our own accounting is unauditable is backwards ordering. Generality work is real but is a
+  feature list, not an epic — and Track F is what will say which parts of it matter.
+
+* docs(roadmap): truth up Track D — seven classes, and the Action waits on Track F
+
+Track D still read '0.3.4' and 'four false-positive classes', and promised the GitHub Action as the
+  next step, which now contradicts Track F's deliberate deferral. afk reads this file verbatim, so a
+  contradiction in it is a contradiction injected into the expander's prompt.
+
+### Features
+
+- **cli**: Graphmark links — surface the classification distribution (#125)
+  ([#131](https://github.com/cdcoonce/graphmark/pull/131),
+  [`3ccf11c`](https://github.com/cdcoonce/graphmark/commit/3ccf11c26028c03739cfa88e67119c230645a22e))
+
+Track F slice 2. Slice 1 made the classification countable; this makes it readable. Counts sitting
+  in a Python object are worthless to a vault owner, and that gap is not cosmetic: the six-release
+  frontmatter-alias defect was legible in this distribution the whole time — 23 links reported
+  broken beside zero resolved via alias — and nobody saw it because no surface printed it.
+
+`graphmark links` emits the block as JSON on stdout with a one-line summary on stderr, so stdout
+  stays pipeable. `check`'s report carries the same block under `links`, appended after `checks` so
+  consumers already parsing that report keep working, and provably unable to change the verdict — a
+  test pins that a passing and a breaching run produce identical `links`.
+
+The byte-stability oracle in test_check.py is updated rather than sidestepped, and now pins a
+  cross-check worth having: max_unresolved_links' actual equals counts.missing, so the gate's
+  flagship number and the distribution behind it cannot silently disagree.
+
+Filed #130 along the way: every CLI example in the README fails. --config and --root live on the
+  parent parser, so argparse only accepts them before the subcommand, while the README documents the
+  opposite in all ten examples. It survived because the suite exclusively uses the working form, so
+  nothing exercised the documented one — the same shape as the rest of Track F, and the reason
+  #130's acceptance criteria require every README example to be executed by a test.
+
+Mutation testing caught that the report's zero-fill was untested: build() seeds all six keys, so
+  only a directly constructed graph exercises it. Covered now.
+
+- **graph**: Per-reason link counts and the conservation law (#124)
+  ([#129](https://github.com/cdcoonce/graphmark/pull/129),
+  [`4ba2ab6`](https://github.com/cdcoonce/graphmark/commit/4ba2ab65b32654af98f3987f2688c18af23c7f02))
+
+Track F slice 1. build sorted every extracted display into one of the six DIAGNOSIS_REASONS and then
+  kept exactly one bucket plus the edges. The other outcomes were decided and discarded, and that
+  silence is why six of the seven correctness bugs in this package's history went unnoticed: each
+  was a mis-bucketing, and nothing in the output made an implausible distribution visible.
+
+graph.link_counts accounts for every display, one bucket each, with all six keys always present in
+  DIAGNOSIS_REASONS order — a zero is a finding, so it must be reported rather than absent.
+  graph.alias_resolved counts resolutions reached through an alias, which is not a DIAGNOSIS_REASONS
+  value but is the distinction that would have made #119 visible.
+
+LinkDiagnosis gains `via` ("stem" or "alias") so the counter reads the classifier's own verdict
+  instead of re-deriving it. Re-deriving is how the two would eventually disagree, which is the
+  failure this repo has spent Track E removing.
+
+The conservation law — sum(link_counts.values()) equals the extractor's total — is asserted on a
+  vault exercising all six outcomes, on the frozen fixtures, and against the pre-existing surface
+  (unresolved occurrences == ambiguous + missing), so the new tally cannot drift from the old one.
+
+On the live 521-note vault the payoff is legible in one line. Healthy: missing 0, alias-resolved 23.
+  The same vault with aliases disabled, which is what the six-release defect actually looked like:
+  missing 23, alias-resolved 0. Same 6226 total either way — nothing vanished, 23 links were in the
+  wrong bucket, and now you can see that.
+
+Purely additive: no metric changes, frozen fixtures byte-identical.
+
+### Testing
+
+- Property-based vault generation — Track F's detector (#126)
+  ([#132](https://github.com/cdcoonce/graphmark/pull/132),
+  [`cd76410`](https://github.com/cdcoonce/graphmark/commit/cd76410087157677f6f6515c94d11057060063eb))
+
+The frozen oracle prevents regression and has never surfaced anything new, because fixtures only
+  encode shapes somebody already thought of, and all seven historical bugs were shapes nobody
+  thought of. This generates vaults nobody designed and asserts what must hold for any content at
+  all.
+
+Two layers, and the second is the one that matters.
+
+STRUCTURAL invariants over generated vaults: conservation (every extracted display lands in a
+  bucket), edges name real notes and never exceed the resolved count, self-links never become edges,
+  back_links mirror out_links, unresolved is exactly ambiguous+missing, aliases never shadow a real
+  note name, and build is deterministic — the headline claim of this package, asserted nowhere until
+  now.
+
+Those all passed on first run, which was the finding. Every one of the seven bugs kept conservation
+  intact; each merely filed a link in the WRONG bucket. So the structural layer would have caught
+  none of them, and shipping only that would have been a detector that cannot see the thing it
+  exists for.
+
+METAMORPHIC relations close that gap. Obsidian treats [[X]], [[X|alias]], [[X#Section]] and [[X.md]]
+  as the same link, so each rewrite must leave the counts and edges identical. Re-injecting the real
+  defects confirms the layer works: #104 (.md), #98 (intra-note), #101 (non-note file), #119
+  (aliases) and the path-qualified whitespace bug each fail a property.
+
+Two of those properties were over-specified on first write — they compared `unresolved`, which
+  echoes the RAW display, so a rewrite legitimately changes it. Comparing it asserts a rewrite does
+  not rewrite anything. They now compare counts and edges, with the reason documented at the helper.
+
+The whitespace property also had to be sharpened: normalization collapses whitespace on its own, so
+  a padded BARE display resolves either way and cannot detect the defect. Only the path-suffix
+  branch is sensitive, which is exactly where the 13 live links were reported broken while pointing
+  at real notes.
+
+hypothesis is a dev dependency only; the shipped runtime dep is still networkx alone. Bounded and
+  derandomized so CI stays fast and failures reproduce.
+
+
+## v0.6.0 (2026-07-25)
+
+### Bug Fixes
+
+- **parse**: Parse block-style frontmatter lists (#118)
+  ([#120](https://github.com/cdcoonce/graphmark/pull/120),
+  [`723c517`](https://github.com/cdcoonce/graphmark/commit/723c517d30732286fd0e6005996fb36d577042f5))
+
+* chore(release): 0.3.4 [skip ci]
+
+* chore(release): 0.4.0 [skip ci]
+
+* chore(release): 0.5.0 [skip ci]
+
+* fix(parse): parse block-style frontmatter lists (#118)
+
+_parse_frontmatter handled scalars, quoted strings and inline lists, but a block list's item lines
+  contain no colon, so the loop skipped them and the bare `key:` line stored "". Every block-style
+  property in a real vault — aliases:, tags: — silently became an empty string instead of a list.
+
+Block form is what Obsidian's own Properties UI writes, so this is the common case, not the edge
+  case, and Document.frontmatter is public: a consumer reading doc.frontmatter["tags"] got "" rather
+  than a list. Not an error, just quietly wrong data.
+
+Item lines are matched on the leading dash BEFORE the key/value split, so an item containing a colon
+  ("- Note: A Subtitle") stays an item. A block closes at the next key rather than merely pausing —
+  without that, a stray indented line later in a malformed note would silently grow the earlier
+  list, which is misattribution rather than the promised fail-soft drop. That distinction survived
+  the first four mutations and now has its own test.
+
+A `key:` with no items still reads as "" — an empty value, not an empty list — so nothing that
+  parsed before changes shape.
+
+Parity: fixture notes use inline or scalar frontmatter only, so no expected.json can move. A test
+  asserts that property directly rather than leaving it as a claim in the commit message.
+
+Still a targeted scan, not a YAML dependency: this runs over every note in a vault and a note
+  someone is mid-edit must not take the graph down.
+
+---------
+
+Co-authored-by: semantic-release <semantic-release>
+
+### Features
+
+- **graph**: Resolve frontmatter aliases in-package (#119)
+  ([#121](https://github.com/cdcoonce/graphmark/pull/121),
+  [`05bb6ce`](https://github.com/cdcoonce/graphmark/commit/05bb6ced17656a3fb3d1d1798068763b26b68588))
+
+graphmark never read frontmatter during resolution, so every link written against an Obsidian
+  `aliases:` entry was reported broken. Measured on a real 521-note vault: stock graphmark reported
+  23 broken links where the actual count was 0, and dropped 17 edges with them. A 100%
+  false-positive rate in max_unresolved_links — the flagship threshold of graphmark check, the one
+  product this repo offers outward. Larger than the four false-positive classes already fixed
+  (#98/#101/#104/#107) combined.
+
+This reverses a documented decision. the-vault's AliasResolver says "naming policy belongs to the
+  seam, so the fallback lives here rather than in the graph algorithm". That holds for idiosyncratic
+  conventions; aliases: is core Obsidian, and this package claims to work on any Obsidian-family
+  vault. Human-triaged: move it in-package, on by default, since a default that silently produces
+  wrong answers is not fixed by a knob nobody knows to flip. resolve_aliases = false restores the
+  old behavior.
+
+That AliasResolver is the oracle, and the live-vault differential is exact: stock graphmark now
+  reports the same broken-link set as the reference implementation, note for note — 0 and 0, from a
+  51-entry alias map.
+
+Its conservative rules are preserved. An alias colliding with any real note name is dropped at index
+  time, not merely outranked, so a note's own title can never be hijacked and an already-ambiguous
+  basename can't be rescued into resolving. An alias claimed by two notes resolves to nothing. A
+  slash-bearing alias is refused when the map is built, because normalization turns "/" into a space
+  and would otherwise make it reachable from a slash-free display — the lookup-side guard alone does
+  not cover that, which mutation testing caught.
+
+One honest note: rule 1 (resolver before alias) is structurally unreachable given the other two
+  rules — no display can match both a catalog key and an alias key — so mutating the order leaves
+  the suite green. It is kept as insurance against a future relaxation and is documented as untested
+  rather than dressed up as covered.
+
+Parity: this changes what resolves, so it is the most parity-sensitive change since extraction. It
+  is safe only because no frozen fixture declares aliases; a test asserts that property directly so
+  it cannot go stale.
+
+
 ## v0.5.0 (2026-07-25)
 
 ### Features

{graphmark-0.5.0 → graphmark-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.5.0
+Version: 0.7.0
 Summary: Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults.
 Project-URL: Homepage, https://github.com/cdcoonce/graphmark
 Project-URL: Repository, https://github.com/cdcoonce/graphmark
@@ -21,6 +21,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: networkx>=3.0
 Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -84,12 +85,32 @@ graphmark siloed                         --root /path/to/vault
 graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
 graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
 graphmark export dot                     --root /path/to/vault > graph.dot
+graphmark links                          --root /path/to/vault
 graphmark check                          --config vault.toml
 ```
 
 Exit codes: `0` success, `1` a `check` threshold breach, `2` a usage or config error. Nothing else
 uses `1`, so CI can trust it.
 
+## `graphmark links` — how every link was classified
+
+```console
+$ graphmark --root /path/to/vault links
+{"total": 6226, "counts": {"resolved": 6169, "ambiguous": 0, "non-note-file": 17, "out-of-scope-note": 0, "missing": 0, "intra-note": 40}, "alias_resolved": 23}
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+JSON on stdout, the one-line summary on stderr, so the output stays pipeable.
+
+Every wikilink lands in exactly one bucket and the buckets sum to `total` — nothing is silently
+dropped. All six reasons are always present, because a zero is a finding: the line above with
+`missing 23 · alias-resolved 0` instead is what a real defect looked like before frontmatter aliases
+resolved, on the same vault with the same 6226 total. Reading the distribution is the fastest way to
+notice the tool is wrong about your vault.
+
+The same block appears in `check`'s report under `links`, as context for the verdict. It never
+changes the verdict.
+
 ## `graphmark check` — vault health as a CI gate
 
 Declare thresholds in the config's `[check]` table, then run `graphmark check` as a build step. It
@@ -185,8 +206,28 @@ graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
 graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
 graph.out_of_scope                            # same, for markdown outside the configured scope
+graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
+graph.link_counts                             # {reason: occurrences} — every link, one bucket each
+graph.alias_resolved                          # how many resolutions came via an alias
+```
+
+`link_counts` accounts for **every** display the extractor produced, one bucket each, and always
+carries all six `DIAGNOSIS_REASONS` — a zero is a finding, not a non-event. The buckets sum to the
+extraction count, so nothing is silently dropped. Reading the distribution is the fastest way to
+notice the tool is wrong about your vault:
+
+```
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+versus the same vault with alias resolution disabled — the shape of a real defect that once shipped:
+
+```
+resolved 6146 · ... · missing 23 · ... · alias-resolved 0
 ```
 
+Same total, 23 links in the wrong bucket.
+
 `catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
 explain a link rather than just resolve it — which notes a bare `[[link]]` collided with, or whether
 a link that failed to resolve points at a real file you deliberately excluded. Value lists are
@@ -253,10 +294,40 @@ Both constants were calibrated against a human-annotated baseline of a real vaul
 rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
 for the method and the measured result.
 
+## Frontmatter aliases
+
+Obsidian's `aliases:` property declares additional real names for a note, so links written against
+one resolve like any other link. Block, inline and scalar forms all work:
+
+```yaml
+---
+aliases:
+  - Mood Tracker
+  - mood-tracker
+---
+```
+
+`[[Mood Tracker]]` now resolves to `2026-04-11-mood-tracker.md` and produces a real edge. On a
+521-note vault this was the difference between **23 reported broken links and 0** — every one of the
+23 a false positive, plus 17 edges that were silently missing.
+
+Three rules keep it conservative:
+
+- **A real note name always wins.** An alias can never hijack a link to a note that actually bears
+  that name.
+- **An alias that collides with any real note name is dropped entirely** — not merely outranked, so
+  an already-ambiguous basename can't be rescued into resolving by someone's alias.
+- **An alias claimed by two notes resolves to nothing**, the same refusal applied to colliding
+  basenames.
+
+Set `resolve_aliases = false` for strict basename-only resolution. `graph.aliases` exposes the
+resolved map.
+
 ## Configuration
 
 ```toml
 root = "."                                    # required unless --root is passed
+resolve_aliases = true                        # resolve frontmatter aliases: (default true)
 scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
 excluded_dirs = [".git", "templates"]         # skip notes under these directories
 rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content

{graphmark-0.5.0 → graphmark-0.7.0}/README.md

@@ -57,12 +57,32 @@ graphmark siloed                         --root /path/to/vault
 graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
 graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
 graphmark export dot                     --root /path/to/vault > graph.dot
+graphmark links                          --root /path/to/vault
 graphmark check                          --config vault.toml
 ```
 
 Exit codes: `0` success, `1` a `check` threshold breach, `2` a usage or config error. Nothing else
 uses `1`, so CI can trust it.
 
+## `graphmark links` — how every link was classified
+
+```console
+$ graphmark --root /path/to/vault links
+{"total": 6226, "counts": {"resolved": 6169, "ambiguous": 0, "non-note-file": 17, "out-of-scope-note": 0, "missing": 0, "intra-note": 40}, "alias_resolved": 23}
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+JSON on stdout, the one-line summary on stderr, so the output stays pipeable.
+
+Every wikilink lands in exactly one bucket and the buckets sum to `total` — nothing is silently
+dropped. All six reasons are always present, because a zero is a finding: the line above with
+`missing 23 · alias-resolved 0` instead is what a real defect looked like before frontmatter aliases
+resolved, on the same vault with the same 6226 total. Reading the distribution is the fastest way to
+notice the tool is wrong about your vault.
+
+The same block appears in `check`'s report under `links`, as context for the verdict. It never
+changes the verdict.
+
 ## `graphmark check` — vault health as a CI gate
 
 Declare thresholds in the config's `[check]` table, then run `graphmark check` as a build step. It
@@ -158,8 +178,28 @@ graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
 graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
 graph.out_of_scope                            # same, for markdown outside the configured scope
+graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
+graph.link_counts                             # {reason: occurrences} — every link, one bucket each
+graph.alias_resolved                          # how many resolutions came via an alias
+```
+
+`link_counts` accounts for **every** display the extractor produced, one bucket each, and always
+carries all six `DIAGNOSIS_REASONS` — a zero is a finding, not a non-event. The buckets sum to the
+extraction count, so nothing is silently dropped. Reading the distribution is the fastest way to
+notice the tool is wrong about your vault:
+
+```
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+versus the same vault with alias resolution disabled — the shape of a real defect that once shipped:
+
+```
+resolved 6146 · ... · missing 23 · ... · alias-resolved 0
 ```
 
+Same total, 23 links in the wrong bucket.
+
 `catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
 explain a link rather than just resolve it — which notes a bare `[[link]]` collided with, or whether
 a link that failed to resolve points at a real file you deliberately excluded. Value lists are
@@ -226,10 +266,40 @@ Both constants were calibrated against a human-annotated baseline of a real vaul
 rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
 for the method and the measured result.
 
+## Frontmatter aliases
+
+Obsidian's `aliases:` property declares additional real names for a note, so links written against
+one resolve like any other link. Block, inline and scalar forms all work:
+
+```yaml
+---
+aliases:
+  - Mood Tracker
+  - mood-tracker
+---
+```
+
+`[[Mood Tracker]]` now resolves to `2026-04-11-mood-tracker.md` and produces a real edge. On a
+521-note vault this was the difference between **23 reported broken links and 0** — every one of the
+23 a false positive, plus 17 edges that were silently missing.
+
+Three rules keep it conservative:
+
+- **A real note name always wins.** An alias can never hijack a link to a note that actually bears
+  that name.
+- **An alias that collides with any real note name is dropped entirely** — not merely outranked, so
+  an already-ambiguous basename can't be rescued into resolving by someone's alias.
+- **An alias claimed by two notes resolves to nothing**, the same refusal applied to colliding
+  basenames.
+
+Set `resolve_aliases = false` for strict basename-only resolution. `graph.aliases` exposes the
+resolved map.
+
 ## Configuration
 
 ```toml
 root = "."                                    # required unless --root is passed
+resolve_aliases = true                        # resolve frontmatter aliases: (default true)
 scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
 excluded_dirs = [".git", "templates"]         # skip notes under these directories
 rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content

{graphmark-0.5.0 → graphmark-0.7.0}/docs/ROADMAP.md

@@ -22,13 +22,14 @@ story** — the priority consumer is the owner's vault seam (`graph_cli.py`), no
 
 ## What's shipped (baseline — do not re-propose)
 
-- **The full engine, v0.3.4 on PyPI**: `parse.py` (wikilink extraction, code-span skipping),
-  `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build` + `unresolved`), `metrics.py`
-  (stats, orphans, hubs, clusters, bridges, siloed_notes, neighborhood, pure-python pagerank,
-  gaps), `check.py` (policy evaluation), `export.py` (JSON/DOT), `cli.py`, `config.py`
-  (`VaultConfig` + `CheckPolicy` + `load_config`), and `dismiss.py` (content-hash weaklink
-  dismissal store). Tracks A, C and D are all closed — read their sections before proposing
-  anything in those areas.
+- **The full engine, v0.6.0 on PyPI**: `parse.py` (wikilink extraction, code-span skipping,
+  frontmatter incl. block lists), `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build` +
+  `unresolved` + `diagnose`/`LinkDiagnosis` + frontmatter aliases), `metrics.py` (stats, orphans,
+  hubs, clusters, bridges, siloed_notes, neighborhood, pure-python pagerank, gaps), `check.py`
+  (policy evaluation), `export.py` (JSON/DOT), `cli.py`, `config.py` (`VaultConfig` +
+  `CheckPolicy` + `load_config`), and `dismiss.py` (content-hash weaklink dismissal store).
+  Tracks A, C, D and E are all closed — read their sections before proposing anything in those
+  areas.
 - **Six frozen differential fixtures** — simple, alt, scoped, selflink, gaps (+ out-of-graph),
   dismiss — plus live-vault parity diffs against the reference engine.
 - **`gaps()` with injected similarity** — graphmark owns the deterministic ranking/filtering
@@ -63,14 +64,17 @@ Shipped: `graph.unresolved`, the `[check]` policy block (`max_orphans` /
 reserved for breach and a byte-stable JSON report, `graphmark.build()` + curated top-level
 re-exports, and a README rewritten around the real surface.
 
-_Where we are (0.3.4):_ the gate works and the vault dogfoods it. The remaining risk is the
-**credibility of its flagship number**. Four false-positive classes have been found and fixed by
-triaging a real vault against the metric — same-note anchors (#98, 19% of the count),
-non-markdown targets (#101, 10%), the `.md` extension (#104), and links to notes that exist but
-are out of graph scope (#107, 7%). A threshold nobody trusts is not a gate.
+_Where we are (0.6.0):_ the gate works and the vault dogfoods it. The remaining risk is the
+**credibility of its flagship number**. Seven false-positive classes have been found and fixed —
+same-note anchors (#98, 19% of the count), non-markdown targets (#101, 10%), whitespace-padded
+displays, the `.md` extension (#104), out-of-scope notes (#107, 7%), frontmatter aliases (#119,
+**23 phantom breaks against an actual 0**), and Unicode NFD/NFC (#123). A threshold nobody trusts
+is not a gate.
 
-_Where we're going:_ keep truthing the metric against live vaults, then the thin GitHub Action
-wrapper — but only once the count is trustworthy enough to fail someone's build.
+_Where we're going:_ **Track F, not the GitHub Action.** Every one of those seven was found by a
+human reading link lists on one vault, which does not scale and has no reason to be finished. The
+Action ships once the accounting underneath it is auditable — see Track F for why that ordering is
+deliberate.
 
 ### Track E — One resolver: absorb the consumer's second link stack (feature track)
 
@@ -97,6 +101,55 @@ point of it). The consumer-side deletion is hand-coded in the vault; the package
 
 _Constraint:_ this is additive. Nothing here may change what resolves or what an edge is.
 
+**CLOSED at v0.6.0.** #110/#111/#112 shipped, and frontmatter aliases moved in-package (#119) —
+the last piece of the consumer's parallel stack. the-workshop#474 deletes the consumer side.
+
+### Track F — Auditable link accounting (the current epic)
+
+_The problem is not any individual bug; it is how they get found._ Every correctness bug in this
+package's history was found the same way: a human reading link lists from **one** vault. Seven so
+far — #98 same-note anchors, #101 non-markdown targets, #104 the `.md` extension, #107 out-of-scope
+notes, #119 frontmatter aliases, #123 Unicode NFD/NFC, plus the whitespace-padded displays fixed
+alongside #107. Six of those seven landed in a single day of hand-triage.
+
+The frozen differential oracle is a **ratchet, not a detector.** It prevents regression superbly and
+has never once surfaced something new. Worse, the single consumer's seam actively _conceals_
+package defects: its `AliasResolver` hid a 23-link error for six releases, because the only vault
+that could have exposed the gap had already patched around it.
+
+_Why the bugs hide:_ the buckets are silent. `build` sorts every extracted display into one of the
+six `DIAGNOSIS_REASONS`, then reports **one** of them. A vault owner sees `N unresolved` and nothing
+about what was suppressed — and six of the seven bugs were _mis-bucketing_, a link filed as
+`unresolved` that belonged in `resolved` or the reverse. Had graphmark printed
+
+```
+3677 edges · 23 unresolved · 0 alias-resolved · 12 out-of-scope · 8 non-note-file · 19 intra-note
+```
+
+the alias gap would have been obvious at a glance: zero alias-resolved beside 23 unresolved is
+visibly wrong. Nobody could see it, so nobody saw it for six releases.
+
+_Where we're going:_ **every extracted display lands in exactly one named bucket; the buckets are
+counted, reported, and bound by a property-tested conservation law.** The aim is not another metric
+— it is to make the package's own answers auditable, so an implausible distribution is visible to
+its owner without a day of triage. That is the mechanism that scales past one vault and one human,
+and it is the strongest possible expression of the "public correctness story" identity.
+
+Sliced as #124 (per-reason counts + the conservation law), #125 (`graphmark links` surfaces the
+distribution), #126 (property-based vault generation — **the detector**; expect it to fail on first
+run, and file what it finds), #127 (implausibility heuristics — advisory only, **not
+autonomous-safe past the exact checks**, since the statistical thresholds need the same human
+calibration gate #112 used).
+
+Track F's own success measure is not slices merged: it is **bugs found by machinery rather than by
+a human reading link lists.** #126's catch rate is the evidence.
+
+_Deliberately deferred behind this:_ the Track D GitHub Action. It is an adoption play, and adoption
+is not this repo's game; more to the point, shipping a gate that fails other people's builds while
+the tool's own accounting is unauditable is backwards ordering. Generality work (Windows paths,
+markdown-style `[text](note.md)` links for wikilink-disabled vaults, non-my-brain schemas) is real
+but is a feature list, not an epic — and this track is what will tell us which parts of it matter.
+
 ### Track B — Judgment the oracle can't cover (human-validated)
 
 - New fixtures on a **different schema** than my-brain have hand-authored expected values → a human

{graphmark-0.5.0 → graphmark-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphmark"
-version = "0.5.0"
+version = "0.7.0"
 description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,7 +27,7 @@ Repository = "https://github.com/cdcoonce/graphmark"
 Issues = "https://github.com/cdcoonce/graphmark/issues"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "ruff>=0.6"]
+dev = ["pytest>=8.0", "ruff>=0.6", "hypothesis>=6.100"]
 
 [project.scripts]
 graphmark = "graphmark.cli:main"

{graphmark-0.5.0 → graphmark-0.7.0}/src/graphmark/__init__.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 
-from graphmark.check import run_check, unresolved_link_count
+from graphmark.check import links_report, run_check, unresolved_link_count
 from graphmark.config import CheckPolicy, VaultConfig, load_config
 from graphmark.dismiss import (
     active_dismissed_sigs,
@@ -33,6 +33,7 @@ from graphmark.graph import (
     LinkDiagnosis,
     NormalizeResolver,
     VaultGraph,
+    build_aliases,
     build_catalog,
     candidates_for,
     diagnose,
@@ -112,6 +113,7 @@ __all__ = [
     "active_dismissed_sigs",
     "bridges",
     "build",
+    "build_aliases",
     "build_catalog",
     "candidates_for",
     "diagnose",
@@ -126,6 +128,7 @@ __all__ = [
     "pagerank",
     "parse_document",
     "record_dismissal",
+    "links_report",
     "run_check",
     "siloed_notes",
     "stats",