[daniloc]

Every bundled language plugin now reads its text through a tree-sitter parser, and the parses that make this affordable are kept in the user's own cache, one file each. Merging this releases 1.11.0: the Release workflow publishes it to npm as latest.

What changes

• Parsers for Python, Go, Rust and TypeScript/JavaScript (web-tree-sitter 0.27.1, Coherence's first runtime dependency).
  • A plugin names treeSitter { parser, queries, resolve }, and the core derives every reading of the language's text from one parse.
  • The hand-written reader slots (source, declares, topLevel, kept) are removed at plugin interface 4.
  • A plugin ejected from 1.10 is refused with its recovery first: eject again from this version.
  • Statements are read whole, across lines. Text inside strings and comments is never read as code.
• TypeScript runs on Coherence's patched build of tree-sitter-typescript 0.23.2, since upstream has merged no grammar change since 2024-11.
  • The patch fixes import('x').T<U> and its kin, members and statements beginning with in, and a bare & in JSX.
  • Results over 17,106 PostHog files:
    • files with errors go from 191 to 52;
    • 85 declarations come back;
    • none is lost.
  • grammars/tree-sitter-typescript/build.sh builds both parsers with no network, from inputs checked by digest. It then compares stock and patched over upstream's corpus, Coherence's own corpus and this repository's source. CI's typescript-parsers job rebuilds them byte for byte.
  • The comparison holds over those inputs alone, and the docs say so. For a misread no corpus holds, the TypeScript plugin's @misread query catches a reserved word read as a name in any file Coherence reads, and orient says so.
• Kept parses live in the user's cache ($XDG_CACHE_HOME/coherence/parses, else ~/.cache), never in a project.
  • Each is a file of its own, named by the text's digest, written once and never changed, so no process merges, locks or reloads.
  • The store is used only where its path is the user's alone, and never when it lies inside the repository being read.
  • Each parse and query stops after a fixed amount of work, so one huge generated file can't take the runtime down.
  • On PostHog's 19,902 Python files:
    • first warm-up: 32 s;
    • the next: 2.0 s;
    • mass: 3.4 s, where parsing every file takes 14.8 s.
• plugin check gains three duties: answers agree, the language server agrees, and every plugin reads one reference project the same way. Also new: plugin shapes, plugin calibrate and plugin compare.
• A dead-end alarm. spec --check, orient and the convergence reading name a component that keeps collecting defects across classes and rounds, and ask a human whether to redesign it. The journal is read across every worktree, and a defect must say where it lies. The alarm is built to help an agent that wants to work well notice a dead end; it is not a defense against an agent gaming its own records.
• Kernel practices: "close a defect" now weighs a redesign at a dead end. "Keep state where it is true" is new, after Data is destiny.
• Prereleases are cut by .github/workflows/prerelease.yml. A read-only build job checks the commit, packs the tarball, checks its parsers against parsers.sha256 and runs plugin check; only the release job can write.
• Includes Rust: wasm-bindgen and UniFFI entrances, examples, and the lists slot #156 (Rust wasm-bindgen and UniFFI entrances), so Rust: wasm-bindgen and UniFFI entrances, examples, and the lists slot #156 can close once this lands.

Review

Eight rounds of blind review ran against this branch. The parse store collected 26 defects over the first rounds, each fixed at the site the reviewer found, until the dead-end alarm named it. It was then redesigned: first moved out of the project, then made one file per parse. The owner acknowledged the dead end as addressed by the redesign (ak-6ae550c5).

The last review (of 766fba1) found shallower faults, each fixed locally in 9887d0f:

• the runtime's limit on a huge file;
• a quadratic loop;
• caches in checkouts and group-writable homes;
• the alarm's accident paths;
• the comparison's claim.

Known

• A session start still stops on an unreadable file in its own journal; spec --check reports it instead (u-561ee937).
• macOS access lists on the cache folder are not read.
• Two flakes are recorded and unexplained: the leak guard's self-test (df-e8424adc) and a Rust overlay test (c-7e051032).
• prerelease.yml's release job has not run yet.
• TypeScript forms that still fail to parse, as with stock (docs/plugins.md):
  • ({ a }?: T) => U;
  • a parenthesized import type;
  • importOriginal<typeof import('x')>();
  • a method named in after another member.

Testing

• npm test: 821 pass, 0 fail, 2 skipped (environmental).
• spec --check: 0 problems. lexicon:check: 0 rejected names.
• build.sh: both parsers rebuilt byte for byte; every difference from stock is intended.
• Every changed bullet was refuted with a staged break that turned its test red on its own assertion, then run batched and alone: 20 of 20 batched, 19 of 19 alone on the final tree.

🤖 Generated with Claude Code