Changelog

Surface follows semantic versioning. This page mirrors releases of the surf CLI. While Surface is pre-1.0 (v0.x), minor versions may include breaking changes.

v0.8.0

Added.

Hubs are now conformant Open Knowledge Format (OKF) concepts — “Surface = OKF + freshness.” A hub’s frontmatter is a superset of an OKF concept: it carries OKF’s type (defaulted to concept so existing hubs are byte-unchanged and keep working), title, tags, and timestamp, and preserves any other frontmatter key verbatim (OKF’s description/ resource, a doc system’s author/created/pinned) in an extra map — the OKF rule that consumers must not drop unknown keys. So a hub drops into any OKF consumer (Google’s Knowledge Catalog, the OKF visualizer, Obsidian, git-backed editors), which read the prose and ignore the anchors: Surface governs. surf new scaffolds type: concept.
Freshness provenance and stable claim IDs. surf verify now records the freshness OKF omits: a stable per-claim id (written once, never regenerated, so it survives prose/anchor edits — the substrate for claim timelines) plus verified_at and verified_commit. The who is deliberately not stored (git blame on the hub records it) — keeping author emails out of tracked files. Provenance is written only when the hash actually changes, so a no-op re-verify stays byte-identical. The --format json Divergence gains an additive id field (no report-version bump).
OKF bundle layout. surf.toml gains a bundles glob: each root is a directory tree of concept files, expanded as <root>/**/*.md. OKF reserved files (index.md, log.md) are recognized and skipped for governance — they hold no claims and never block the gate.
surf lint OKF advisories. A Warn (never a block) for an unknown frontmatter key that looks like a typo of a known one (recovering the fail-closed signal below), a Warn when an anchored hub has no headline (summary/title/description), and a Warn for a dangling OKF cross-link in a hub body (OKF tolerates broken links, so this never blocks).

Changed.

Frontmatter no longer rejects unknown keys (OKF requires consumers to preserve them). This is a deliberate, narrow relaxation of the gate’s fail-closed posture: a mistyped frontmatter key that previously hard-blocked now parses and earns a surf lint warning instead. Unknown keys inside an anchor item still fail closed — anchor items are Surface’s own data, not OKF’s.
summary is now optional (an OKF concept may carry only description).

v0.7.0

Added.

refs hub composition. A hub’s refs: now compose other hubs: a path relative to the referencing hub (./resolve.md), optionally > symbol to address one claim within the target (matched against that claim’s at: anchor). surf lint blocks a ref that doesn’t resolve to a loaded hub, points at its own hub, or names a claim the target lacks — the same fail-on-typo discipline as covers. The surf check gate then propagates staleness one hop: a hub that directly references a stale hub (or a stale claim within one) inherits a referenced_stale divergence and fails the gate, so the signal that flags a dependency flags everything composed on it. Propagation is one-hop by construction (built only from base divergences), so a chain A → B → C doesn’t cascade. The repo’s own hubs now declare their cross-hub refs, and the two prior doc-pointing refs were reclassified to prose links.
surf lint consolidation nudges. Two advisory warnings push hubs away from the “claim-log” shape (one claim per function) and toward onboarding docs: a claim-log warning when a hub has several claims and never once uses a multi-site at: list, and a thin-prose warning when a multi-claim hub’s body is too sparse to onboard a reader. Both are non-blocking (exit 0), mirroring the existing over-/under-anchoring nudges.

Changed.

surf suggest reframed. Human output now reads as a list of undocumented symbols, not a list of claims to write: it groups symbols by file and emits a multi-site at: skeleton with prose-first scaffolding, steering authors toward coarse, system-level claims. --format json is unchanged.
surf new scaffold ships a prose-first template (## How it works / ## Boundary headings and a multi-anchor example claim) so a fresh hub is shaped like an onboarding doc.
Hash recipe v2 — the bound/free split. The canonical hash now alpha-renames only bound identifiers (a symbol’s own name, parameters, locals, loop/range/comprehension variables, with/catch aliases, generic params, destructuring binders) and emits every free identifier verbatim (external members, call targets, types, enum/constant references, object keys, decorators). Re-pointing an anchored span at a different symbol is now loud even when the name occurs once — PointsTier.TIER_1 → TIER_2, getHighest → getLowest, a bare helper(x) → other(x), a parameter type Foo → Bar, an object key { alpha } → { beta } — where before it passed the gate silently while the claim’s prose became false. Consistent local/parameter renames stay quiet, as before. This subsumes the earlier member-access-only first cut and the Python decorator special case. A new in-tree differential harness (surf-core/tests/differential_hash.rs) gates the change: zero benign-rename regressions, 100% catch on the semantic free-swap corpus across all four languages. Binding detection is tree-sitter-only and fail-closed; the one accepted approximation (match-arm pattern identifiers are treated as free) is documented in Hash recipes. Covers TypeScript, Go, Rust, and Python.
Versioned stamps. Stored hashes now carry their recipe: a v2 stamp is prefixed 2:, a bare 12-hex stamp is an implicit v1. surf check verifies each stamp under its own recipe, so existing v1 stamps keep passing (with a one-line nudge) until surf verify re-stamps them as v2 — one pass per repo. An unrecognized stamp prefix fails closed. See Hash recipes. Action on upgrade: run surf verify once.

v0.6.3

Added.

Hubs may now declare advisory covers globs (repo-root-relative, same dialect as config.hubs). The field is accepted, stored, and lint-validated — a malformed glob blocks, and a hub whose globs don’t match its own anchored files warns — but the verdict never reads it: surf check is byte-for-byte identical whether or not a hub declares covers. The louder coverage pass that consumes these globs stays deferred (#94, part of #5).
TypeScript suggest now enumerates exported class methods (Class > method) by default — matching Go and Python — so a class-heavy file no longer reports “no unanchored public symbols found.” suggest --all additionally proposes the exported class itself and non-callable const/let/var declarations (object/array/scalar). The “Rust/TypeScript --all changes nothing” note now fires only for Rust.
A failed flat TypeScript anchor that looks like a method now hints the chain spelling: EffectiveTierService.getForUsers or a bare getForUsers reports did you mean `EffectiveTierService > getForUsers`? — the Class > method syntax was previously undiscoverable.

Fixed.

TypeScript exported non-callable const/let/var (export const TIER_MAP = { ... }) is now anchorable — previously only function-valued declarators resolved, so the const maps most prone to drift had no anchor target. Mirrors #28’s Python fix.

v0.6.2

Added.

surf suggest --all now proposes Go exported top-level const, var, and type declarations (including structs), matching what the resolver already accepted — the Go edition of #52’s Python fix. The “Python-only” note added for #79 now fires only for Rust and TypeScript, where --all still changes nothing.

Fixed.

Python @overload sets are one anchorable unit: consecutive same-name stubs plus their implementation resolve as a single logical symbol, so the bare name works without @N and the hashed span covers stubs and impl — a signature change in any overload now trips the gate, where previously only the implementation body was hashed and the typed contract could drift silently. suggest’s proposed path for overloaded functions now lints clean instead of failing its own resolver. Anchors that used the old name@N workaround to pick a stub or the implementation should re-anchor to the bare name and re-verify.
Python symbols bound inside module-level if/try blocks — TYPE_CHECKING guards, version gates, try/except ImportError fallbacks — now resolve by name like their unconditional siblings, and are enumerated by suggest and the lint coverage nudge. A name bound in multiple branches is reported ambiguous and disambiguated with the existing @N mechanism.
surf check --files now warns on stderr when a glob matched no anchored files, and exits non-zero when every glob matched nothing — a typo’d pattern no longer scopes the gate to nothing and reports a clean run, mirroring suggest’s existing zero-match behavior.
surf lint coverage warnings (and check’s malformed-hub divergences) no longer print a dangling empty claim: line when there is no claim to show.
The release workflow now polls the npm registry after publishing and fails the run if any package version never becomes fetchable, instead of trusting npm publish’s exit code — the registry has silently dropped freshly published versions post-publish.

Changed.

surf suggest --all prints a note when the scan includes non-Python files: --all currently only proposes non-callable symbols for Python, so its silence on Go/Rust/TS is no longer mistakable for “this file has no non-callables”.

v0.6.1

Changed.

surf stats now reads the whole history window from a single streamed git log --name-status instead of spawning a diff-tree/rev-parse/ls-tree triple per commit. Hub claim state is propagated incrementally — a hub is re-read (git show) only at commits that touched it — so the git-spawn count scales with hub edits rather than history length. On a 13k-commit repo this is the difference between minutes and seconds; metrics are byte-identical to the previous implementation. Requires git ≥ 2.31 for --diff-merges=first-parent.

Fixed.

ARM64 Linux is now a first-class install target. Releases publish an aarch64-unknown-linux-gnu binary, and both install.sh and the npm channel (@gradient-tools/surface) resolve it for the host. Previously ARM64 Linux fell through to a missing asset; the installer now succeeds there rather than failing on a 404.
surf for distinguishes a path that is a directory from one that does not exist, instead of reporting both the same way — the error now points at the actual problem.

v0.6.0

Added.

surf suggest --all additionally proposes the non-callable anchor targets resolve already accepts but suggest previously hid: top-level classes, module-level constants and type aliases, and class attributes (Python). The default stays callables-only (functions + methods) to avoid over-anchoring fatigue. Closes the gap where those kinds were anchorable by hand yet undiscoverable via suggest.
npm distribution: install via npm install @gradient-tools/surface or run ad-hoc with npx @gradient-tools/surface check. A thin shim resolves the prebuilt binary for the host from per-platform optionalDependencies (macOS Apple Silicon, Linux x86_64) — no postinstall download step. Published from CI on each release with provenance attestation.
Release integrity: each published binary now ships a <asset>.tar.gz.sha256 checksum, and the curl | sh install script (and the GitHub Action that wraps it) verifies the download against it before installing. A missing checksum or a mismatch aborts the install — fail closed — rather than running a corrupted or tampered binary.

Changed.

surf stats is much faster on large histories. It previously recomputed the hub claim set at every commit and its parent, each spawning git ls-tree plus a git show per hub — roughly 2 × commits × hubs subprocesses. The claim set is now memoized by commit SHA, with each before rev canonicalized to its parent’s SHA so it reuses the parent commit’s already-computed state. Metrics are unchanged.

Fixed.

surf lint’s under-coverage nudge is no longer workspace-blind and no longer skips methods. Coverage is now computed across the whole workspace, so splitting one file’s claims across two hubs no longer makes each hub warn about the symbols the other one anchors; and the measured public surface now includes methods (Type > method), not just top-level functions, matching what suggest proposes.
surf for, surf check --files, and surf stats now fail loudly on malformed input instead of returning a falsely-reassuring success. surf for errors on a nonexistent/mistyped path, a directory, or a trailing slash (instead of “no hubs anchor” + exit 0); invalid --files glob syntax and invalid surf.toml hub globs now error instead of being silently dropped (#53, #38).

v0.5.0

Fixed.

surf check now fails closed. A hub whose frontmatter can’t be parsed previously slipped through silently (exit 0, unenforced); it now surfaces as an Unresolvable divergence that blocks the run. A hashing error is likewise reported as Unresolvable instead of being counted clean.

Changed.

Hub iteration is unified behind Workspace::iter_hubs(), shared by check, lint, suggest, and for. Each command carries the per-hub parse result explicitly, so the error case can no longer be handled inconsistently from one command to the next.
CI now runs the test suite and dogfood self-check on macOS (macos-14) in addition to Linux, matching the Apple-Silicon binary that releases ship. Windows is documented as unsupported .

v0.4.0

Added.

surf for <path> [symbol] — reverse lookup: list every hub and claim anchored into a file, so you can pull up the documentation governing code before you edit it (the inverse of suggest). Read-only and always exits 0; --format json emits a versioned {version, path, matches} envelope. An optional trailing symbol narrows to anchors whose first segment matches.
surf stats [--since <date>] [--until <date>] — adoption metrics from git history (advisory, never a gate): the rubber-stamp rate (re-stamps that changed a claim’s stored hash but left its prose untouched) and the in-place update rate (commits touching an anchored file that re-sealed the claim in the same commit). One commit = one PR (merges excluded); heuristics are documented in docs/guides/stats.md. Errors (non-zero) when git history is unavailable.
surf suggest now proposes methods, not just top-level functions: Python class methods and Go methods are enumerated as file > Type > method anchors (matched by exported Go receiver type; Python async/sync mirrors de-duped). On method-oriented codebases this surfaces the bulk of the public API that was previously invisible to suggest. Rust impl/TS class methods remain top-level-only.

Changed.

surf suggest distinguishes a glob that matched no files from a clean “nothing to suggest”: it warns on stderr and exits non-zero when every glob was empty, so a typo’d path no longer reads as success. Coverage is now keyed on the full file > seg > seg anchor path, so anchoring one method no longer suppresses its siblings.

v0.3.2

Documentation.

The docs site (surface.gradientdev.xyz) is now generated from this repo on release: each v* tag regenerates the Starlight site’s pages and changelog from docs/ and CHANGELOG.md and opens a sync PR, so the site no longer drifts from canonical docs.
docs/reference/commands.md is now governed by surf check itself — a hub anchored to the clap command/flag surface blocks the gate when the CLI and its reference drift.
Pinned Connorrmcd6/surface@vX.Y.Z Action refs in the README and docs are now derived from Cargo.toml at release, and the Examples page description is quoted so it parses under the site’s strict YAML.

v0.3.1

Documentation.

Reposition around documentation governed like code for fast-moving codebases, led by the context-rot story (a context file that’s accurate when written and rots as the code moves because nobody knows it exists or where to find it). Dropped the older accusatory framing.
Slim the README to a pitch + compact quickstart that links out; the full reference now lives in docs/. Restructured docs/ into a site-ready tree (getting-started/, reference/, guides/) with title/description frontmatter, mirroring the docs site (surface.gradientdev.xyz); this repo’s docs/ is the source of truth.
Bring the docs current with 0.3.0: the versioned --format json envelope, the per-claim ignore_literals option, Python non-callable anchors, file-rename --follow, and decorators in the hashed span.

v0.3.0

Added.

Python: at: now resolves non-callable symbols — module-level constants and type aliases (X = …, X: T = …, PEP 695 type X = …) and class-level attributes (Class > attr, including annotation-only). Previously only functions, methods, and classes resolved.
Per-claim ignore_literals: true frontmatter option — excludes string-literal content from a claim’s hash so a copy edit inside the anchored span no longer re-opens the gate. Logic edits (operators, numbers, structure) are still caught. The stored hash is computed in this mode, so it travels with the claim rather than a CLI flag.
surf verify --follow and surf lint now follow file renames via git rename detection: a moved file makes lint warn (and point at --follow) instead of hard-blocking, and --follow rewrites the anchor’s path — only when the code is otherwise unchanged. Best-effort and git-dependent; the deterministic surf check verdict never depends on it.

Changed.

Python decorators are now part of an anchored function/class’s hashed span, and a decorator’s name is kept verbatim (not alpha-renamed) — so adding/removing a decorator, changing its arguments, or swapping it (@cache → @lru_cache, @staticmethod → @classmethod) trips the gate. Previously decorators were excluded from the span entirely.
Breaking (JSON): surf check --format json now emits a versioned envelope { "version": 1, "divergences": [...] } instead of a bare array. The contract is additive-only within a major version; a breaking change bumps version. Consumers should read .divergences and tolerate unknown fields.

v0.2.1

Documentation.

Precisely scope “cosmetic”: a literal value is part of the hashed AST, so editing a string literal — including user-facing copy — inside an anchored span trips the gate. “Cosmetic” means only whitespace, comments, and consistent renames. Added a FAQ entry and a note to anchor the narrowest symbol so unrelated literal edits don’t re-open a claim.

v0.2.0

Added.

surf check scoping: --files <globs> evaluates only claims whose anchored file(s) match, and an explicit --base <ref> diff-scopes the gate to claims whose files changed since the merge base. Omitting --base keeps a full check (enrichment falls back to HEAD).
--format json for surf lint and surf verify, mirroring surf check. lint emits structured findings; verify emits per-anchor outcomes (stamped/followed/unchanged/skipped) plus counts.
Advisory surf lint granularity warnings (never blocking): a near-whole-file anchor span, a hub with too many anchors, and public functions in an anchored file that no claim covers.
surf lint enforces the AGENTS.md pointer block: when AGENTS.md carries a  block, it must link the hubs directory (and that directory must exist) so agents are pointed at the hubs to search — never duplicating or enumerating them. Opt-in; blocks on a missing/dangling pointer.
surf suggest <globs> — scans source for top-level public functions that no hub anchors yet and prints a copy-pasteable starter hub. Suggestions only: never writes a file or stamps a hash.
surf_core::public_fns — enumerates a file’s top-level public functions (backs the under-coverage warning and surf suggest).

Changed.

An explicit surf check --base <ref> now diff-scopes the gate to claims whose files changed, in addition to feeding advisory old_code/magnitude. Previously --base only fed enrichment and every claim was still checked. CI that passes --base explicitly will now check fewer claims; omit --base for a full check.

v0.1.1

Fixed.

resolve: resolve const-bound call-expression functions (TS/JS).
verify: skip unchanged anchors instead of re-stamping, so a no-op verify leaves hub files byte-identical.

Changed.

Releases: dropped Intel macOS (x86_64-apple-darwin); prebuilt binaries cover macOS (Apple Silicon) and Linux (x86_64). Other targets build from source.

v0.1.0

Initial release — the MVP gate that surfaces docs↔code divergence.

Added.

AST-canonical hashing via bundled, version-pinned tree-sitter grammars: quiet on cosmetics (formatting, comments, consistent renames), loud on logic. Advisory tree-edit magnitude.
Anchor resolution: the file > A > B path grammar with @N disambiguation; scope-set resolution so Type > method resolves uniquely.
Hub format (markdown frontmatter), surf.toml workspace discovery, and per-claim combined hashing across multi-site at: lists.
Commands: surf lint, surf check (the gate), surf verify (re-seal, with --follow for renames), plus surf init and surf new for authoring ergonomics.
Language support: TypeScript/TSX, JavaScript/JSX, Rust, Python, and Go.
Distribution: GitHub Action, pre-commit hook, and install.sh; Apache-2.0 license.