GithubStar/codegraph
1
0
Fork 0
mirror of https://github.com/colbymchenry/codegraph.git synced 2026-10-19 06:22:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(design): plugin API design — surfaces, config, trust, compat (CG-63)

Browse Source 
The design doc the rest of epic CG-62 (GH #1376) implements: v1 exposes
framework/semantic plugins only (FrameworkResolver + synth passes), with
language providers deferred to the kernel-aware spike CG-72.

Two proposals from the issue are argued down on evidence: the plugin list
lives in the committed root `codegraph.json`, not `.codegraph/config.json`
(everything in .codegraph/ is gitignored), and plugins load on the write
path rather than through CodeGraph.open() (which is deliberately lazy-loaded
off the MCP startup path).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Colby McHenry
2026-09-02 12:33:41 -05:00
parent 7ec9ef1818
commit 24c446be4b
1 changed files with 739 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/plugin-api.md
+739
View File
@@ -0,0 +1,739 @@
# Plugin API — surfaces, config, trust, compat
**Status:** design, awaiting review (CG-63). Nothing here is implemented yet.
**Implements:** GH [#1376](https://github.com/colbymchenry/codegraph/issues/1376) · epic CG-62.
**Gates:** CG-64 (internal registry), CG-65 (config), CG-66 (types package), CG-67
(loader), CG-68 (end-to-end), CG-69 (example + harness), CG-70 (docs), CG-71
(validation), CG-72 (language-provider spike).
**Verified against the tree at:** `feature/CG-62`, 2026-09-02. Every file:line in
this doc was read; re-check them before trusting a claim.
Goal, in the issue's words: *implement a plugin → install it → list it in config →
sync*. An internal team ships proprietary framework/route support without forking
core and without waiting on a release. Built-ins register through the same path, so
every release exercises the plugin API.
This doc makes the decisions the rest of the epic implements. Where the issue text
proposed a default, it is either confirmed with a reason or argued down; two
proposals are argued down (`.codegraph/config.json`, and loading through
`CodeGraph.open()`). Genuinely open items are collected in
[Open questions](#open-questions) rather than papered over.
---
## 1. Two surfaces, phased
**v1 ships one surface: framework / semantic plugins.** A plugin contributes:
| Contribution | Interface | Where it runs today |
|---|---|---|
| Framework resolver | `FrameworkResolver` (`src/resolution/types.ts:218`) | parse workers (`extract`), main + resolver workers (`detect`/`resolve`/`claimsReference`/`postExtract`) |
| Synthesis pass | `SynthPassDef` (`src/resolution/callback-synthesizer.ts:3528`) | resolver workers, merged on the main thread |
`FrameworkResolver` is already plugin-shaped — `detect` / `resolve` /
`claimsReference` / `extract` / `postExtract`, all pure over a
`ResolutionContext` — which is why it is the v1 surface and not a new invention.
`SynthPassDef` is the same idea for whole-graph passes: `run(queries, ctx, yield)`
returns edges and persists nothing itself, so a pass is a pure function of
committed graph state. That is ytfh44's `SemanticPlugin.augment(graph) →
GraphPatch` with the names this codebase already uses.
**Language providers are deferred** to spike CG-72. See
[§10](#10-why-language-providers-are-deferred).
Deliberately *not* in v1, and why:
- **Node-synthesis hooks** (the Lombok-style `synthesizeMembers` seam inside
`extractClass`). A plugin that wants nodes emits them from a framework
resolver's `extract()`, which already returns `{ nodes, references }`. Opening a
second node-producing seam before the first one has an external user is
speculative.
- **Query/read-time hooks.** No plugin code runs when a graph is *read* — see
[§3](#3-the-fact-everything-else-follows-from-plugins-are-a-write-path-concern).
- **Anything per-request or per-tool-call.** No HTTP hook, no MCP tool
contribution, no network capability. Same section.
marcelovani's three-layer model (core registry → official built-ins → user
plugins) is adopted as-is for layer 1 and 2 semantics: the registry is the only
registration path, and the ~35 built-in resolvers in
`src/resolution/frameworks/index.ts` go through it (CG-64). Layer 2 as *separate
published packages* is explicitly out of scope per the issue ("splitting every
built-in into its own repo") — built-ins stay in-tree, they just stop being a
hardcoded array.
---
## 2. Where the extension points are today
Read this before the rest; the constraints in §3–§9 come from it.
| Thing | Location | Property that matters |
|---|---|---|
| `FRAMEWORK_RESOLVERS` | `src/resolution/frameworks/index.ts:42` | plain array, **order is semantic** |
| `registerFrameworkResolver()` | `src/resolution/frameworks/index.ts:142` | exists, **zero callers**, replaces by name |
| `detectFrameworks()` | `.../index.ts:116` | already try/catches a throwing `detect` |
| `SYNTH_PASSES` | `src/resolution/callback-synthesizer.ts:3548` | merge order = array order, **first-seen wins** a duplicate `(source,target)` |
| Pass dispatch **by name** into a worker | `src/resolution/resolver-worker.ts:101` | `SYNTH_PASSES.find(p => p.name === msg.pass)` |
| Framework lookup **by name** in a parse worker | `src/extraction/parse-worker.ts:95` | `getAllFrameworkResolvers().filter(r => frameworkNames.includes(r.name))` |
| Project config | `src/project-config.ts` (`codegraph.json`, root, committed) | mtime-cached, **keyed by project root** |
| `.codegraph/` ignore rule | `src/directory.ts:652` | `*` + `!.gitignore` — **everything in it is gitignored** |
| Index staleness stamp | `indexed_with_extraction_version`, `CodeGraph.isIndexStale()` (`src/index.ts:1230`) | the existing "re-index recommended" channel |
| MCP lazy engine load | `src/mcp/engine.ts:22-27`, `:252` | `CodeGraph.open()` is deliberately **off** the MCP startup path |
Two of these are load-bearing and easy to miss:
**Plugins must load in three process contexts, not one.** The main thread detects
frameworks and ships their **names** to parse workers, which look the names up in
their *own* copy of the registry (`parse-worker.ts:95`); resolver workers each
construct a full `ReferenceResolver` and run synth passes looked up by *name*
(`resolver-worker.ts:101`). A plugin registered only on the main thread would have
its `extract()` silently skipped — and worse, `frameworksNeedDecode` would compute
`false`, sending the file down the kernel raw-buffer fast path, so the failure mode
is "no error, fewer nodes". Registration therefore happens in **every** context
that builds a resolver or runs a pass, from one resolved plugin set (§4.4).
**Config is loaded per call site, keyed by root — not threaded through `open()`.**
`loadExtensionOverrides(root)` and friends are module-level, mtime-cached, and
root-keyed precisely so the daemon can host several projects in one process
(`project-config.ts:104`). Plugins follow that pattern (§5.3).
---
## 3. The fact everything else follows from: plugins are a write-path concern
> **A plugin's code runs only while the graph is being written — `index`, `sync`,
> and the watcher's sync. No read path ever loads plugin code.**
Every reader — `codegraph_explore`, `codegraph_node`, the CLI's `query` /
`context` / `affected`, the `ui` server — reads nodes and edges a plugin already
wrote. Their shape is the engine's own (`NodeKind`/`EdgeKind` in `src/types.ts`),
so a reader cannot tell a plugin's edge from a built-in's except by the provenance
metadata it deliberately carries (§4.3).
This single rule settles four otherwise-hard questions at once:
- **MCP attach latency** (§8): zero plugin work on `serve --mcp` startup, zero on a
tool call. The existing lazy-load of the whole CodeGraph chain off the MCP
startup path (`engine.ts:22`, worth ~800ms) stays intact because plugins do not
hang off `open()`.
- **ui-server security** (§6): the loopback server never executes plugin code, so
the DNS-rebinding boundary in `src/ui-server/security.ts` is untouched and there
is nothing new behind it. Plugins get no request hook and no network capability
*by construction* — not by a rule someone must remember.
- **Determinism** (§7): a plugin influences the graph at exactly one point in time
(a write run), so "same inputs → same graph" is checkable by re-indexing.
- **Blast radius of a broken plugin** (§9): it degrades an index run. It can never
make a *query* fail, which is what would teach an agent to abandon codegraph.
---
## 4. The plugin contract
### 4.1 Module shape
A plugin package's entry module default-exports a **factory**:
```ts
import type { CodeGraphPlugin, PluginContext, PluginContributions } from '@colbymchenry/codegraph-plugin-api';
export default function plugin(ctx: PluginContext): PluginContributions {
return {
frameworks: [acmeRoutesResolver(ctx.options)],
synthPasses: [],
};
}
```
```ts
interface PluginContext {
/** Absolute, resolved project root. */
projectRoot: string;
/** The `options` object from this plugin's config entry, verbatim (unvalidated). */
options: Record<string, unknown>;
/** Running engine version, for a plugin that wants to feature-detect. */
engineVersion: string;
/** Structured diagnostics. Plugins must not write to stdout — it is the MCP transport. */
log: { warn(msg: string, meta?: object): void; debug(msg: string, meta?: object): void };
}
interface PluginContributions {
frameworks?: FrameworkResolver[];
synthPasses?: SynthPass[];
}
```
A factory, not a static object, because options are per-project and the same
package may be loaded for two roots in one daemon process. The factory must be
**cheap and side-effect-free** — it constructs resolvers, it does not scan the
repo. It is called once per (root, plugin) per process.
`ctx.log` exists because `console.log` in a plugin would corrupt the MCP stdio
transport. This is a hard rule for plugin authors, stated in the authoring guide
(CG-70), not enforceable at runtime.
### 4.2 Manifest, and why it lives in `package.json`
```jsonc
// package.json of @acme/codegraph-plugin-internal-routes
{
"name": "@acme/codegraph-plugin-internal-routes",
"version": "1.2.0",
"main": "dist/index.js",
"codegraph": {
"id": "acme-internal-routes",
"apiVersion": 1,
"engines": ">=1.5.0",
"capabilities": ["frameworks"]
}
}
```
| Field | Required | Meaning |
|---|---|---|
| `id` | yes | Stable identifier. Namespaces every contribution (§7.2), appears in diagnostics and in edge provenance. `[a-z0-9][a-z0-9-]*`, ≤ 64 chars. |
| `apiVersion` | yes | Integer major of the plugin API this plugin was written against (§9). |
| `engines` | no | semver range against the **engine** version. Absent = any. |
| `capabilities` | yes | Declared contribution kinds: `"frameworks"`, `"synthPasses"`. Returning a contribution that was not declared is a load error. |
**The manifest lives in `package.json`, not in the module's exports**, for one
reason: it is the only version of the check that happens *before* the plugin's code
executes. `require()` runs module top-level code; a manifest read from an export
can only gate the factory call, which is already too late. Reading
`package.json` lets the loader reject an `apiVersion: 2` plugin on a v1 engine
without ever evaluating it.
*Exception, stated honestly:* a plugin loaded by **path specifier** (a single file
committed in a non-Node repo, §5.2) may have no `package.json`. Those may export a
named `manifest` object instead, and the compat check then happens after module
evaluation. The doc says so out loud rather than pretending the guarantee is
uniform; the real protection for that case is the trust model (§6), not the check.
**On mismatch — `apiVersion` unsupported, `engines` unsatisfied, manifest missing
or malformed, `id` colliding — the plugin is skipped with a diagnostic and the run
continues.** Never a crash, never a partial registration. (§9 covers what a
mismatch *says*.)
### 4.3 What contributions must guarantee
Promoted from in-tree convention to public contract:
1. **`postExtract` idempotency and id preservation.** The contract already
documented at `src/resolution/types.ts:246-255` becomes public verbatim: the
node `id` MUST be preserved so existing edges survive; `qualifiedName` SHOULD be
preserved so a second run can recover the original in-file form. `postExtract`
runs again on **every incremental sync**, so a non-idempotent pass corrupts the
graph slowly rather than loudly.
2. **Node ids must be namespaced.** Built-ins use scheme-prefixed ids
(`route:<file>:<line>:<METHOD>:<path>` — `frameworks/express.ts:171`;
`expo-module:` for cross-platform pairs). A plugin's synthetic node ids must be
prefixed `plugin:<id>:` so two plugins can never collide and so a node can be
traced back to what made it.
3. **Synthesized edges carry provenance.** `provenance: 'heuristic'` plus
`metadata.synthesizedBy = '<plugin id>'` and, where the wiring site is known,
`metadata.registeredAt = 'file:line'` — the same shape the built-in
synthesizers use.
4. **A plugin edge must say what it means.** `ContextBuilder` renders a
synthesized hop from a **closed** `synthesizedBy` switch
(`src/context/index.ts:405-421`) whose fallback is the string `event …`. An
unknown plugin value would therefore render as a fabricated "event" hop — the
exact overclaiming CLAUDE.md forbids. So the contract requires
`metadata.label` (a short human phrase, e.g. `"Acme route → handler"`) on any
plugin-synthesized edge, and CG-68 must make the renderer prefer
`metadata.label` and fall back to `via <plugin id>` — never to `event`.
5. **Purity.** No wall clock, no randomness, no network, no dependence on file
visit order or on state carried between files. See §7.3.
6. **No direct DB writes.** Contributions return data; the engine persists it.
`ResolutionContext` is a read interface and stays one.
### 4.4 One resolved plugin set per run
At the start of a write run the main thread produces a **resolved plugin set**:
for each config entry, `{ id, version, resolvedPath, options }`, in config order.
That object — not the config file path — is what parse workers and resolver
workers receive in their init message.
Consequence: every context loads the *same* modules with the *same* options even
if `codegraph.json` is edited mid-run, and a worker never re-reads or re-resolves
config. This is the direct analogue of the main thread resolving the language and
shipping it to the parse worker (`parse-worker.ts:82-86`) rather than letting each
worker detect independently.
Workers load only what they need: `"frameworks"` → parse workers and resolver
workers; `"synthPasses"` → resolver workers only. A plugin declaring neither is
never loaded in a worker at all.
---
## 5. Configuration
### 5.1 The file is `codegraph.json` — **not** `.codegraph/config.json`
The issue proposed `.codegraph/config.json` "since the dir already exists".
Rejected, on evidence:
- **`.codegraph/` is entirely gitignored.** `init` writes `.codegraph/.gitignore`
containing `*` + `!.gitignore` (`src/directory.ts:645-657`) so transient files —
the DB, `daemon.pid`, sockets — are never committed. A plugin list is the
opposite kind of state: it must be committed, reviewed, and shared, or the whole
premise ("a teammate clones and gets the same graph") fails. It is also the file
a security reviewer must be able to see in a diff (§6).
- **A committed project config already exists.** `codegraph.json` at the project
root (`PROJECT_CONFIG_FILENAME`, `src/project-config.ts:32`) is documented as
"committed … that a team shares through version control" and already carries
`extensions`, `include`, `exclude`, `includeIgnored`, `deprioritize`. A second
config file would be a second answer to "where do I configure codegraph".
- The `.codegraph/` dir does get one job here, and it is the right one: the
machine-local trust stamp (§6.3), which must *not* be committed.
### 5.2 Schema
```jsonc
{
"plugins": [
"@acme/codegraph-plugin-internal-routes",
{
"name": "@acme/codegraph-plugin-rpc",
"options": { "protoDir": "api/proto" }
},
{ "name": "./tools/codegraph/legacy-routes.js" }
]
}
```
- Entries are objects `{ name, options?, replaces? }`. A bare string is sugar for
`{ name }`, normalized at parse time.
- `name` is a **module specifier**: a bare package name (resolved from the project
root, §7.1) or a project-relative path beginning `./` or `../` that stays inside
the root.
- `options` is passed to the factory verbatim. The engine does not validate it;
the plugin does (and reports through `ctx.log`).
- `replaces?: string[]` — built-in resolver names this entry displaces. See §7.2.
Validation follows `project-config.ts`'s existing posture exactly: **an invalid
entry is warned-and-skipped, never fatal; a malformed file degrades to the
zero-config default.** A non-array `plugins`, an entry without a string `name`, an
absolute path, a path escaping the root — each is one `logWarn` and a skip.
Unknown keys are already ignored by `parseConfig`, so adding `plugins` is
backward-compatible with older engines — with one honest caveat: an older engine
silently produces a graph *without* the plugin's edges. The index stamp (§5.4)
makes that visible on the machine that has the newer engine, not on the old one.
### 5.3 One load path — the existing one
`loadPluginEntries(rootDir): PluginEntry[]` joins `loadExtensionOverrides`,
`loadExcludePatterns`, … in `src/project-config.ts`, sharing the same
mtime-cached, root-keyed `loadParsedConfig`.
The issue proposed that "ALL entry points read it through one load path in
`CodeGraph.open()`". The *intent* is right — one load path — but `open()` is the
wrong place:
- `open()` is deliberately lazy-required off the MCP startup path
(`src/mcp/engine.ts:22-27`) and is not called at all until the first tool call
touches a project. Hanging plugin resolution off it puts plugin `require()` cost
on the first tool call, which is the latency that matters most (§8).
- The daemon hosts several roots in one process; root-keyed module-level caching is
precisely why `project-config.ts` is built the way it is.
So: **config parsing** goes through the one existing loader, from any entry point,
at any time. **Plugin loading** happens once per write run, on the write path, from
the resolved set (§4.4). Both are single paths; they are just not the same path.
### 5.4 When the plugin list changes
Two mechanisms, no hot reload (explicitly out of scope in the issue):
- **Index stamp.** A write run records `indexed_with_plugins` in
`project_metadata` — the sorted `id@version` list actually loaded. `codegraph
status` compares it to the currently resolved set and, on a difference, prints
the same kind of hint `isIndexStale()` already drives: *the plugin set changed
since this index was built — run `codegraph index`.*
- **Live daemon.** Editing `codegraph.json` already triggers
`FileWatcher.refreshScope()` and a full rescan (`src/sync/watcher.ts:581,614`).
That rescan runs with the plugin set the **process** loaded at start, so a newly
listed plugin will not take effect until restart. This is a real, narrow drift
(the same class of bug #1590 fixed for scope fields): the rescan's graph and a
restarted process's graph differ. v1 handles it by *saying so* — the stamp
mismatch above is written by that rescan too, so `status` and the index summary
both report "plugin set changed; restart the MCP server / re-index" — rather than
by pretending a `require()` cache can be invalidated. Recorded as a known
limitation in the authoring guide (CG-70).
---
## 6. Trust and security
### 6.1 What is actually true
A plugin is `require()`d into the engine process. It has the full authority of that
process: filesystem, network, `child_process`. **CodeGraph does not sandbox
plugins, and v1 does not claim to.** The security property on offer is *consent*,
not containment: code runs because a human put its name in a version-controlled
file that shows up in review.
Stating this plainly is the point. Node's `--permission` model could bound a
plugin's fs/net access, but it applies process-wide and the engine itself needs
broad fs access; a per-plugin sandbox means a separate process with an IPC-shaped
contribution API, which is a much larger project than #1376. Out of scope for v1,
noted in [Open questions](#open-questions) as the natural v2 lever.
### 6.2 The two rules
1. **Explicit listing only.** Only entries present in the project's committed
`codegraph.json` are ever loaded. **No auto-discovery** — not by
`codegraph-plugin-*` name prefix, not by scanning `node_modules`, not by a
`codegraph` key found in an arbitrary installed package. Confirming the issue's
proposal, and the reason is worth keeping in the doc: with prefix discovery, any
transitive dependency that renames itself becomes an execution vector inside a
tool that runs over the user's entire source tree.
2. **Specifier confinement.** A bare name resolves only through the *project's own*
resolution paths (§7.1) — i.e. something the user installed. A path specifier
must stay inside the project root; absolute paths and `../` escapes are rejected
at parse time, consistent with the engine's existing path-refusal posture
(`validatePathWithinRoot`).
### 6.3 The hostile-repo case, and the trust stamp
The uncomfortable corollary of "the config is committed": cloning a hostile
repository and running `codegraph init` would execute whatever `./tools/evil.js`
its `codegraph.json` lists. This is the same exposure class as VS Code workspace
tasks or an ESLint config's plugins, and it deserves an explicit answer rather than
a footnote.
Proposal — **workspace-trust, machine-local**:
- The first time a project's plugin set is loaded, the engine records a stamp in
`.codegraph/plugins-trust.json` (gitignored by construction, per-machine): the
hash of the normalized `plugins` array plus the resolved ids/versions.
- When the stamp is absent or does not match:
- **interactive CLI** (`codegraph init` / `index` / `sync` on a TTY) → prompt
once, listing exactly what will be loaded, and record the answer;
- **non-interactive** (MCP serve, the daemon, CI, `--yes`) → **skip all plugins**
with a diagnostic telling the user to run `codegraph plugins trust` (or index
once interactively). Never execute unreviewed plugin code from a context that
cannot ask.
- `CODEGRAPH_PLUGINS=0` disables plugin loading entirely, mirroring
`CODEGRAPH_KERNEL=0`. A `--no-plugins` flag on `init`/`index`/`sync` does the
same for one run.
Note the split: a **bare package** specifier can only load if the user already ran
`npm install`, which already executes that package's install scripts — the marginal
risk is small. A **path specifier** ships inside the repo, so it is the case the
prompt exists for. If the prompt is judged too much UX for v1, the fallback is
"path specifiers require the stamp, bare specifiers do not" — listed in
[Open questions](#open-questions).
### 6.4 Interaction with the ui-server loopback boundary
None, by construction (§3): `codegraph ui` is a read surface, it never loads plugin
code, and no plugin hook runs per HTTP request. The boundary in
`src/ui-server/security.ts` — loopback `Host` check, no CORS headers,
`resolveProjectFile` as the single read chokepoint — is unchanged and unextended.
v1 grants plugins **no network capability of any kind**: no listener, no route, no
outbound helper in `PluginContext`. A plugin that dials out is doing it with raw
Node APIs, which is exactly what §6.1 says the trust model is for.
---
## 7. Module resolution, registry order, determinism
### 7.1 Resolving a specifier inside the bundled runtime
CodeGraph ships its own Node (`scripts/build-bundle.sh`, currently v24.16.0), so
the engine's own `require` resolves against the *bundle*, not the user's project.
Plugins must resolve against the **project**:
```ts
const req = createRequire(path.join(projectRoot, 'package.json'));
const resolved = req.resolve(specifier); // bare name → project node_modules; './x' → in-repo file
```
`createRequire` from the project root is the same mechanism the kernel loader
already uses for our own native binary (`src/extraction/kernel/loader.ts:151`).
- **CJS and ESM both supported.** `require()` first; on `ERR_REQUIRE_ESM` fall back
to `await import(pathToFileURL(resolved))`. On the bundled Node 24, `require()`
of an ESM graph without top-level await already works, so the fallback is mostly
for TLA modules. The default export is unwrapped from `.default` in either case.
- **Native addons are banned in v1.** A `.node` binding in a resolved specifier is
a load error with a specific message. The bundled runtime is Node 24.x; addons in
a user's `node_modules` are built against whatever Node they installed with
(commonly 20 or 22), and the module ABIs differ — the failure without the ban is
an opaque `NODE_MODULE_VERSION` error attributed to codegraph. We control our own
kernel binary's build; we cannot control a plugin's.
- **wasm is allowed** and is the recommended escape hatch for native-speed work —
the engine already loads wasm grammars, and a wasm module is ABI-portable across
the bundled runtime.
- Resolution failure (`MODULE_NOT_FOUND`) is a skip-with-diagnostic naming the
package and suggesting `npm install`, not a crash.
**Non-Node projects** (a Go or Rails repo with no `node_modules`) get the path
specifier: commit the plugin — a small built JS file or a vendored package
directory — anywhere in the repo and list it as `./tools/codegraph/plugin.js`.
Recommended over the alternatives: `.codegraph/plugins/` with its own
`package.json` would be gitignored (§5.1) and so invisible to teammates and to
review; a global `~/.codegraph/plugins` dir is neither per-project nor
version-controlled. A team that wants dependency management in a non-Node repo can
put a real `package.json` in `tools/codegraph/` and list
`./tools/codegraph/node_modules/@acme/plugin` — no new mechanism needed. (Open
question 2 if the maintainer wants a first-class install dir anyway.)
### 7.2 Registry order and duplicates
- **Built-ins first, in their current array order; then plugins, in config order.**
Never interleaved, never sorted. `FRAMEWORK_RESOLVERS` order is semantic (the
comments in `frameworks/index.ts` explain which resolver must see a reference
first), and `SYNTH_PASSES` order decides which duplicate `(source, target)` edge
wins — the cross-tier pass sits before the emitter pass *on purpose*
(`callback-synthesizer.ts:3550-3554`).
- **Duplicate ids are a load error**, not a silent replace. Today
`registerFrameworkResolver` splices out a same-named resolver and pushes the new
one — fine as a dead export, wrong as a public API: a plugin could shadow
`express` by accident and no one would know. CG-64 changes it to reject a
duplicate (skip + diagnostic).
- **Displacing a built-in is explicit and belongs to the user, not the plugin
author**: `{ "name": "@acme/drupal", "replaces": ["drupal"] }` in config. The
named built-ins are removed from the registry for that project, and `status`
reports the displacement. This is what makes CG-71's acceptance test possible —
porting `drupalResolver` out-of-tree and diffing the graph requires turning the
in-tree one off.
- **Synth pass names** are namespaced on registration as `<plugin id>:<name>` so
the name-keyed dispatch into resolver workers (`resolver-worker.ts:101`) can
never collide with a built-in pass.
- `SYNTH_PROGRESS_STEPS` is pinned by a test to the pass count; with plugin passes
the count becomes per-run, so CG-64 must make it a function of the *effective*
registry rather than a module constant.
### 7.3 Determinism
**Requirement: same repo + same plugin set → same graph, byte-for-byte in node and
edge sets.** Two runs that differ mean a plugin is impure, and a non-deterministic
graph is unreviewable — it breaks incremental-sync convergence (the invariant in
`.kommandr/memory/sync-rebuild-convergence-invariant.md`) and every A/B measurement
the project relies on.
What the engine guarantees: fixed registry order; synth-pass results merged in
registry order regardless of execution order (already true — passes persist
nothing until the ordered merge, `callback-synthesizer.ts:3730-3738`); the same
resolved plugin set in every worker (§4.4).
What the plugin must guarantee: no clock, no randomness, no network, no
cross-file mutable state, no dependence on visit order. The plugin test harness
(CG-69) enforces it the only way that is honest — index twice and diff — and
CG-71's validation gate includes a double-index diff on a real repo.
---
## 8. Performance budget
The constraint that dominates: **MCP attach is already borderline at ~2–3s**
(CLAUDE.md, retrieval performance), and an agent that starts its first turn before
codegraph attaches runs the whole task without codegraph.
Commitments:
1. **No plugin work on the MCP startup path, ever.** Plugins load on the write path
only (§3), not in `CodeGraph.open()`, not in `MCPEngine.ensureInitialized`, not
on a tool call. Attach latency is structurally unchanged — there is no code to
run, so there is nothing to measure or regress.
2. **Plugins load at the start of an index/sync run**, after config resolution and
before extraction; the cost is `require()` + one factory call per plugin per
context.
3. **Per-plugin timing is surfaced**: load ms and factory ms per plugin, per
context, behind `CODEGRAPH_PLUGIN_TIMINGS=1` (mirroring
`CODEGRAPH_SYNTH_TIMINGS`), and a one-line total in the index summary. A plugin
whose load exceeds **1s** gets a warning naming it — a slow plugin should be
attributable without a profiler.
4. **The multiplier is explicit.** Load cost is paid once per process/thread that
needs the plugin: main thread + N parse workers (frameworks) + M resolver
workers. Capability-gated loading (§4.4) keeps a synth-pass-only plugin out of
parse workers entirely.
5. **Gate (CG-71):** with the ported plugin installed, (a) fresh-index wall clock on
a control repo within run-to-run noise of the no-plugin build, (b) the explore
call budget and Read/Grep counts unchanged on the standard flow questions, (c)
MCP attach unchanged. Measured with the harness and model policy CLAUDE.md
mandates (Sonnet, ≥2 runs per arm, CLI shim blocked).
Budgeting the *plugin's own* work is the plugin author's problem, with one engine
guardrail: a plugin's synth pass runs under the same cooperative-yield discipline
as a built-in (`yieldToLoop` is passed into `run`), because a pass that blocks the
main thread trips the liveness watchdog and gets the process SIGKILLed — the #1091
/ #1122 failure class. The authoring guide states this as a rule with the failure
it prevents.
---
## 9. Error isolation, diagnostics, and compatibility
### 9.1 Failure policy
| Failure | Behavior |
|---|---|
| Manifest missing / malformed / `apiVersion` unsupported / `engines` unsatisfied | Skip the plugin. Diagnostic. Run continues. |
| Module not found / resolution refused (absolute path, escape, `.node`) | Skip. Diagnostic naming the fix. Run continues. |
| Throw at module scope or in the factory | Skip. Diagnostic with the message and the plugin id. Run continues. |
| Throw inside `detect` / `resolve` / `claimsReference` / `extract` / `postExtract` / a synth pass | **Disable that contribution for the session** on the first throw, log once with plugin id + hook + message, continue indexing. |
| Anything above, in an MCP context | **Never `isError`.** |
Disabling on first throw rather than swallowing every throw is deliberate: a hook
that throws once per file would produce megabytes of log and a silently
half-populated graph. Disabling is bounded and honest — the graph is missing that
plugin's contribution, and `status` says which and why. It matches the existing
posture around synthesis (a pass that fails on a worker is retried once, then
skipped with a printed reason, `callback-synthesizer.ts:3778-3788`) and around
`detect` (already try/caught, `frameworks/index.ts:116-127`).
`isError: true` is reserved for security refusals and genuine malfunctions
(`src/mcp/tools.ts:78-89`); one or two of them early in a session make an agent
stop calling codegraph entirely. A plugin problem is a *user configuration*
problem: it belongs in `status` and in the index summary, never in a tool response.
### 9.2 Where diagnostics surface
- **Index summary** — one line per plugin: `id@version — frameworks: 1, passes: 0
(loaded in 34ms)`, and a warning line per skipped/disabled plugin.
- **`codegraph status`** — a `Plugins:` block after `Backend:`/`Journal:` listing
each configured entry with its state (`loaded` / `skipped: <reason>` /
`disabled: <hook> threw <message>`) and any built-ins it `replaces`. Because
`status` is a *different process* from the index run, the last run's plugin
diagnostics are persisted in `project_metadata` under `plugins_last_run` (JSON)
alongside `indexed_with_plugins` (§5.4).
- **Never** in MCP tool output, and never on stdout from a plugin (§4.1).
### 9.3 Versioning and compatibility policy
- **The types package** — `@colbymchenry/codegraph-plugin-api` (CG-66) — is
versioned **independently of the engine** and is the only public surface. It
exports `CodeGraphPlugin`, `PluginContext`, `PluginContributions`,
`FrameworkResolver`, `SynthPass`, `ResolutionContext`, and the graph types
(`Node`, `Edge`, `UnresolvedRef`, `NodeKind`, `EdgeKind`, `Language`).
- **`apiVersion` is an integer major.** The engine declares which majors it
accepts. v1 accepts `1` only. When a breaking change ships as major 2, the engine
accepts `{1, 2}` for **at least two engine minor releases**, warning in `status`
that major 1 is deprecated, then drops it in a major engine release with a
CHANGELOG `### Breaking Changes` entry.
- **In the contract:** the interfaces above, the required members of
`ResolutionContext`, the `postExtract` id/idempotency rules, node-id namespacing,
edge provenance/label requirements, registry ordering.
**Not in the contract:** the *optional* members of `ResolutionContext` (they may
come and go; plugins already have to feature-detect them, which is why they are
optional in-tree), additive `NodeKind`/`EdgeKind` values, built-in resolver
internals, and anything a plugin reaches by importing from
`@colbymchenry/codegraph` directly rather than from the types package.
- **Publishing:** mirror `@colbymchenry/codegraph-ui` — built and asserted in CI,
`"private": true`, packed only behind an env flag (`scripts/pack-npm.sh`) — and
keep it unpublished until CG-71 proves the API by re-implementing a built-in
out-of-tree with an identical graph. Publishing an API we have not used
externally is how it gets frozen wrong.
- **Adding a built-in framework resolver in-tree is not a plugin-API breaking
change**, but it does change extraction output, so it keeps bumping
`EXTRACTION_VERSION` as today.
---
## 10. Why language providers are deferred
Deferred to spike **CG-72**, for reasons that are architectural rather than
schedule-driven:
- **The TS extractor is the fallback path, not the hot path.** Extraction routes
through the Rust kernel when `isRouted(language) && kernelSupports(language)`
(`src/extraction/kernel/index.ts:155`), with the WASM/TS extractor as the
deferral path. Freezing a public plugin API around `LanguageExtractor` would
publish the legacy architecture as the contract — ytfh44's point on #1376, and
the right one.
- **The language axis is a closed union, not a registry.** `Language` is
`(typeof LANGUAGES)[number]` (`src/types.ts:124`) and `EXTRACTORS` is
`Partial<Record<Language, LanguageExtractor>>`
(`src/extraction/languages/index.ts:40`). A runtime-registered language means
opening that union everywhere it is used — grammars, detection, kernel routing,
branch guards, framework `languages` filters. That is ytfh44's phase 1 and 2, and
it is a bigger job than everything in this doc combined.
- **Language knowledge is not only in extraction.** Import rules, member-call
syntax, chained-call behavior and type inference live in `src/resolution/`. A
language plugin that only supplies extraction still needs core edits, so shipping
one would be a promise the seam cannot keep.
- **The right boundary already exists.** The kernel's ABI-versioned, file/batch-
grained buffer contract is a better long-term extension point than a per-AST-node
callback API, and it is backend-neutral by construction.
The cost of *not* deciding is visible: #1563 asks, in as many words, "which layer
should a new language target now?" CG-72 answers it. Until then the honest position
— stated in the authoring guide (CG-70) — is: **framework and semantic behavior is
pluggable today; a new language is still a core contribution**, and here is the
issue tracking the change.
The capability-levels idea from that comment (parser / symbols / imports / local
calls / cross-file calls / type resolution / framework semantics, each ✓ / partial
/ —) is worth adopting when the language surface lands. v1's `capabilities` field
is deliberately the coarse contribution-kind list; it is forward-compatible with a
richer per-language matrix.
---
## Open questions
1. **Trust prompt in v1?** §6.3 proposes a machine-local trust stamp plus an
interactive prompt, with non-interactive contexts skipping plugins. It is the
right security posture and it is real UX work. Alternative: require the stamp
only for **path** specifiers (code shipped inside the repo) and let bare
installed packages load unprompted, on the grounds that installing them already
executed their install scripts. *Recommendation: ship the stamp, prompt only for
path specifiers in v1.*
2. **A first-class install dir for non-Node repos?** §7.1 recommends committed path
specifiers and no new mechanism. If the maintainer wants `codegraph plugins
install` with its own dir, it must live somewhere committed (`tools/codegraph/`,
not `.codegraph/`), and it is a new sub-project's worth of npm plumbing.
*Recommendation: no; revisit if plugin authorship actually takes off.*
3. **Do plugin synth passes run in resolver workers in v1?** §4.4 says yes, since
parse workers already need plugin loading for `extract()` and the fallback path
(a pass that fails on a worker retries on the main thread) already exists.
Main-thread-only would be simpler but serializes plugin passes on exactly the
repos where synthesis is expensive. *Recommendation: worker-side.*
4. **`replaces` on the config entry vs the manifest.** Config (§7.2) puts the
decision with the person who owns the repo; a manifest field would let a plugin
author displace a built-in for every user who installs it. *Recommendation:
config only.*
5. **Publish the types package in v1?** §9.3 recommends prepared-not-published
until CG-71 passes, mirroring `codegraph-ui`. The counter-argument is that an
unpublished package makes external authorship awkward (plugin authors would
vendor the types). *Recommendation: unpublished through CG-71, publish with the
release that ships CG-68.*
6. **Per-plugin sandboxing** (§6.1) is out of scope for v1. If it ever becomes a
requirement, the shape is a separate process with an IPC contribution protocol —
which the file/batch-grained boundary in CG-72 would also want. Worth keeping
the two in the same conversation.
---
## What each downstream task takes from here
| Task | Consumes |
|---|---|
| **CG-64** internal registry | §2 (the three contexts), §7.2 (order, duplicate rejection, `replaces`, namespaced pass names, `SYNTH_PROGRESS_STEPS` becomes per-run) |
| **CG-65** config | §5 (file choice + schema + `loadPluginEntries` + warn-and-skip posture + `indexed_with_plugins`) |
| **CG-66** types package | §4 (module shape, manifest, contribution guarantees), §9.3 (what is and is not in the contract, publishing model) |
| **CG-67** loader + lifecycle | §4.4 (resolved set), §6 (trust), §7.1 (resolution, ESM/CJS, native ban), §9.1–9.2 (failure policy, diagnostics) |
| **CG-68** end-to-end | §3 (write-path only), §4.3.4 (renderer must honour `metadata.label`, never fall back to `event`), §5.4 |
| **CG-69** example + harness | §7.3 (double-index determinism check), §4.1 (`ctx.log`, no stdout) |
| **CG-70** docs | §6.1 (say plainly that plugins are unsandboxed), §5.4 (no hot reload), §8 (cooperative yield), §10 (a new *language* is still a core contribution) |
| **CG-71** validation | §7.2 (`replaces` makes the built-in port possible), §8.5 (the perf gate) |
| **CG-72** language spike | §10 |
## References
- GH [#1376](https://github.com/colbymchenry/codegraph/issues/1376) — the issue,
plus marcelovani's three-layer comment and ytfh44's two-surface / kernel-boundary
comment.
- GH [#300](https://github.com/colbymchenry/codegraph/pull/300) — the blocked Drupal
contribution that motivates the epic; CG-71 ports it out-of-tree.
- GH [#1563](https://github.com/colbymchenry/codegraph/issues/1563) — "which layer
should a new language target now?"; the cost of leaving §10 unanswered.
- `docs/design/framework-coverage.md` — what a framework resolver has to produce
for each of the three pictures (routes, navigation, guards).
- `docs/design/callback-edge-synthesis.md`,
`docs/design/dynamic-dispatch-coverage-playbook.md` — what a synthesis pass is
for and the validation bar it is held to.
- `docs/design/native-extraction-kernel.md`, `docs/design/rust-kernel-migration-plan.md`
— the seam §10 defers to.