Extension Vocabulary Registry
While Aburi's core schema has a vocabulary fixed by strict enums, language/framework/effect plugins have an extensible "loose" vocabulary. This document defines the registration mechanism for that extension vocabulary.
See: ir-schema.md §5.2 / §9.2 / §16 Plugin manifest: aburi.plugin.v1.json
1. Purpose
Reasons for organizing the extension vocabulary:
- Discoverability: make it possible to query what is registered in a given Aburi installation (CLI / diff renderer / IR consumers)
- Validation: verify at runtime that the extKind / effect.id values a plugin generates stay within what its manifest declared
- Documentation: hold, in machine-readable form, what each extension value "means"
- Conflict detection: stop with an error when two or more plugins declare the same identifier
Schema-level validation (aburi.ir.v1.json) only guarantees pattern matching. Deciding semantically whether "this value may be used in this project" is the responsibility of this registry.
2. Extension targets (4 kinds)
| Target | Location in the IR | Format |
|---|---|---|
extKind | Symbol.extKind | <ns>(:<segment>)+ |
| Effect id (extension) | Symbol.effects[].id | x-<ns>:<action> |
derivedBy strings | Symbol.derivedBy[] | free-form (convention: <ns>:<reason>) |
| Framework ids | Component.frameworks[] | [a-z][a-z0-9-]* |
The vocabulary is declared via the manifest described in §3 of this document.
3. Plugin manifest
Each plugin has exactly one manifest, in which it declares its name, its type, and all vocab it provides.
3.1 Format
The manifest is the manifest property of the plugin object the module exports: its default export, a plugin export, or the first top-level export carrying a manifest, in that order. Neither package.json nor a standalone file is read for it.
// type=effects plugin (effects only, e.g. lifecycle hooks)
{
"$schema": "https://aburi.dev/schema/aburi.plugin.v1.json",
"name": "effects-nest",
"version": "1.0.0",
"type": "effects",
"xPrefix": "nest", // owns x-nest:* (§5.2)
"engines": { "aburi": "^1.0.0" },
"provides": {
"effects": [ // individual enumeration
{ "id": "x-nest:lifecycle.on-module-init", "description": "..." }
],
"effectPrefixes": [], // wildcard ownership (§3.3)
"extKinds": [], // type=effects may not declare extKinds
"extKindPrefixes": [],
"derivedByPrefixes": ["effects-plugin:nest"],
"frameworks": [] // type=effects may not declare frameworks
}
}
// type=framework plugin (boundary recognition, extKind assignment)
{
"$schema": "https://aburi.dev/schema/aburi.plugin.v1.json",
"name": "framework-nestjs",
"version": "1.0.0",
"type": "framework",
"engines": { "aburi": "^1.0.0" },
"provides": {
"effects": [], // type=framework may not declare effects
"effectPrefixes": [],
"extKinds": [
{ "id": "framework:nestjs:controller", "baseKind": "class", "description": "..." }
],
"extKindPrefixes": ["framework:nestjs"],
"derivedByPrefixes": ["framework:nestjs"],
"frameworks": ["nestjs"]
}
}As official npm packages these are split into two: @aburi/effects-nest and @aburi/framework-nestjs.
A type: lang manifest also declares languageId, the <language> token every Symbol id the plugin mints opens with ("languageId": "ts", multi-language-id.md Rule L-1). The schema makes it optional, so that a lang manifest written before the field stays a valid v1 document (§9.5), and the registry requires it of every lang manifest. Like xPrefix for effects plugins, it belongs to one type: an effects or framework manifest that declares one is refused.
3.2 Individual enumeration vs prefix ownership
There are two styles of vocab declaration:
| Style | Form | Use |
|---|---|---|
| Individual enumeration | effects: [{id, description}] | Values are finite and stable, with high documentation value (published plugins) |
| Prefix ownership | effectPrefixes: ["x-acme"] | Values change frequently / are numerous / plugin under iterative development |
Both may be combined. With effects: [{id: "x-acme:explicit"}] + effectPrefixes: ["x-acme"], the plugin owns all of x-acme:*, and x-acme:explicit additionally resolves to its individual description.
3.3 Prefix format
- Elements of
effectPrefixes[]match^x-[a-z][a-z0-9-]*$(no trailing:; a following:<action>is implied) - Elements of
extKindPrefixes[]match^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)+$(at least 2 segments required, i.e.<ns>:<sub-ns>or deeper)
The 2-segment minimum on extKindPrefixes is deliberate. Allowing single-segment ownership such as bare framework would let multiple framework plugins fight over the same top-level namespace, breaking the registry's prefix exclusivity. Including the plugin name, as in <ns>:<plugin-id>, lets framework:nestjs and framework:fastify coexist.
A prefix means "one or more namespace segments owned by this plugin". A plugin declaring extKindPrefixes: ["framework:acme"] may freely emit framework:acme:controller / framework:acme:job etc. at runtime.
3.4 Identifier conventions
| Field | Format |
|---|---|
name | ^[a-z][a-z0-9-]*$ |
version | semver |
type | lang / effects / framework |
provides.effects[].id | ^x-[a-z][a-z0-9-]*:[a-z][a-z0-9.-]+$ |
provides.effectPrefixes[] | ^x-[a-z][a-z0-9-]*$ |
provides.extKinds[].id | ^[a-z][a-z0-9-]*(:[a-z][a-z0-9.-]*)+$ |
provides.extKindPrefixes[] | ^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$ |
provides.extKinds[].baseKind | IR SymbolKind enum |
provides.derivedByPrefixes[] | ^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$ |
provides.frameworks[] | ^[a-z][a-z0-9-]*$ |
These are machine-validated by aburi.plugin.v1.json.
provides.extKinds[].baseKind says what kind of Symbol the extKind describes; it does not constrain Symbol.kind. A plugin may give the extKind to a Symbol the language plugin read as another kind, as framework:next:route (baseKind: "function") goes to a route handler that is a const because its value cannot be seen to be a function.
4. Registration lifecycle
aburi startup
↓ read the plugin lists from config.effects / frameworks / languages
↓ resolve each plugin (npm resolution, or an in-project path)
↓ obtain the manifest (§3) and schema-validate it against aburi.plugin.v1.json
↓ register in the registry (conflict resolution, §6)
↓ start the extraction pipeline
↓ during extraction, the registry verifies every extKind / effect.id a plugin returns:
is it declared / under an owned prefix?
not covered → exit with an error (plugin implementation bug)
with the --discover flag → warn only and continue, record in aburi-vocab-discovered.json (§11.5)Plugins not listed in the config are not loaded. Explicit opt-in.
A refusal at registration ends the run before extraction starts. aburi scan exits 3 and names the config entry that loaded the plugin ahead of the registry's reason (cli-spec.md §5.4). A refused frameworkHints entry (§11.3) is a config error instead, exit 2, naming the entry.
5. Namespaces
5.1 Central reservations (no plugin may declare these)
| Prefix | Purpose |
|---|---|
core:* | The Aburi core engine itself |
aburi:* | Aburi's own metadata |
_:* | Testing/reserved |
framework:hint:* | Auto-prepended for frameworkHints (Tier 3) (§11.3). npm plugins may not declare it |
5.2 Ownable namespaces by type
| Prefix | Ownable by type | Notes |
|---|---|---|
fp:* | lang only | 1 ns = 1 language paradigm; sub-namespaces are individually owned by plugins. Concrete fp:adt / fp:match / fp:effect semantics are locked in fp-extension-impl.md |
oop:* | lang only | Same as above |
meta:* | lang only | Same as above |
framework:* | framework only | Sub-namespaces (framework:nestjs:) are individually owned by plugins |
x-* | effects only | x-<xPrefix>: form. xPrefix is declared explicitly in the manifest (default: name with the effects- prefix removed, e.g. effects-prisma → prisma) |
There is no distinction between "official plugins" and "third-party". Ownership is manifest-declaration based; conflicts are detected at startup.
5.3 Exclusive ownership of sub-namespaces
The framework: prefix is shared by multiple type: framework plugins, but each sub-namespace (framework:nestjs: / framework:react:) is exclusively owned by the single plugin that declared it.
The same applies to fp: / oop: / meta:: each sub-namespace is owned by exactly one plugin.
6. Conflict resolution
6.1 Duplicate declarations
| Situation | Behavior |
|---|---|
Two plugins declare the same effects[].id | startup error |
Two plugins declare the same extKinds[].id | startup error |
One plugin declares the same effects[].id or extKinds[].id twice | startup error |
Two plugins declare the same effectPrefixes[] | startup error |
Two plugins declare the same extKindPrefixes[] | startup error |
Two plugins declare the same frameworks[] name | startup error |
Two plugins declare the same derivedByPrefixes[] | startup error |
Two plugins declare prefixes of one kind (effectPrefixes[], extKindPrefixes[] or derivedByPrefixes[]) where one nests under the other (framework:acme and framework:acme:jobs) | startup error |
One plugin declares two extKindPrefixes[], or two derivedByPrefixes[], where one nests under the other | startup error. Each list is compared with itself only: the same string in both lists, as every framework plugin writes it, is accepted |
Plugin A declares extKinds[].id: "framework:acme:job" and plugin B declares extKindPrefixes: ["framework:acme"] | startup error (B's prefix subsumes A's id) |
Two plugins with the same name and different manifests | startup error (an identical manifest is idempotent, V9) |
Two plugins declare the same languageId | startup error (multi-language-id.md Rule L-1) |
A type: lang manifest declares no languageId, or one outside [a-z][a-z0-9]* | startup error |
A manifest declares languageId: "slice" | startup error (a Slice id opens with slice:, Rule L-11) |
A type other than lang declares languageId | manifest validation error (schema if/then), and a startup error from register |
A type other than effects declares x-* | startup error |
A type other than lang declares fp:* / oop:* / meta:* | startup error |
A type other than framework declares framework:* | startup error |
The prefix part of x-<prefix> does not match xPrefix (default: name with effects- removed) | manifest validation error |
A type: effects plugin declares extKinds / extKindPrefixes / frameworks | manifest validation error (schema if/then) |
A type: framework plugin declares effects / effectPrefixes, or declares extKinds outside the framework: prefix | manifest validation error |
A type: lang plugin declares effects / effectPrefixes / frameworks, or declares extKinds outside (fp|oop|meta): | manifest validation error |
A manifest holding a value JSON cannot carry (such as undefined) | manifest validation error |
Mitigation: forcing the plugin namespace via x-<plugin-name>: naturally resolves effect-id conflicts between third parties.
6.2 Violating central reservations
Any declaration that includes a centrally reserved namespace from §5.1, at either the prefix or the id level → startup error.
6.3 Undeclared values at extraction time
If a plugin's extraction logic generates an extKind / effect.id that the emitting plugin itself does not declare (individually or through an owned prefix) → the entire extraction exits with an error (vocab-undeclared, exit 3). A core effect id is owned by no plugin and passes. The check runs when the value is emitted: an effect as each call is classified, an extKind once the framework plugins have classified the Symbol, charged to the framework plugin that assigned it, or to the language plugin when none replaced its own.
This is a fail-safe against "a plugin silently starts using new vocabulary and breaks time-series comparison".
Exception: with strict off (config.strict: false, --no-strict or aburi scan --discover) this is downgraded to a warning and recorded (§11.5). A value from a file whose Symbols do not reach the IR (withdrawn, or abandoned at its time budget) is not recorded, since the record names Symbols the Document would not hold.
A plugin can also ask for the check itself, through the registry it is handed (assertEffectDeclared / assertExtKindDeclared, §7). The refusal then arrives as the registry's error rather than the core's, under the same code, and ends the run with exit 3 all the same: the code decides, not the class carrying it. The registry does not read strict, so strict off does not downgrade this one — the plugin asked for the refusal.
7. Registry API (consumer side)
interface VocabRegistry {
// lookup (direct by id, or via an owned prefix)
findEffect(id: string): EffectVocab | null
findExtKind(id: string): ExtKindVocab | null
findFramework(name: string): FrameworkVocab | null
findDerivedByOwner(value: string): PluginManifest | null
// ownership checks
isEffectOwnedBy(id: string, pluginName: string): boolean
isExtKindOwnedBy(id: string, pluginName: string): boolean
// enumeration
listEffects(): EffectVocab[]
listExtKinds(): ExtKindVocab[]
listFrameworks(): FrameworkVocab[]
listPlugins(): PluginManifest[]
// validation (at extraction time)
assertEffectDeclared(id: string, byPlugin: string): void
assertExtKindDeclared(id: string, byPlugin: string): void
}findEffect("x-acme:custom-action") returns the entry with its description when x-acme:custom-action is individually enumerated; if it is covered only by prefix ownership, it returns the owning plugin's information with description=null.
8. CLI
aburi vocab (cli-spec.md §8) loads the configured plugins and frameworkHints entries, registers their manifests as a scan would, and lists what the registry then holds, the core effect ids included, without scanning:
aburi vocab list # show all vocab
aburi vocab effects # effect ids and prefixes
aburi vocab extkinds # extKinds and prefixes
aburi vocab plugins # list plugins
aburi vocab who-owns x-nest:lifecycle.on-module-init # the plugin that owns this id
aburi vocab list --json # the same, as JSONwho-owns resolves a value through findEffect, findExtKind, findFramework and findDerivedByOwner (§7), so it answers as the extraction-time check would: an id a manifest enumerates resolves to its description, one only a prefix covers to the prefix's owner with no description.
9. Verifiable properties (test criteria)
| ID | Input | Expected |
|---|---|---|
| V1 | Load a single plugin's manifest | All vocab registered in the registry |
| V1a | parsePluginManifest / loadPluginManifest given JSONC that names one key twice in an object, at any depth, or names __proto__ at all | manifest validation error naming the key, its object and the line. A manifest exported from a TypeScript module does not pass through JSONC, and repeating a key there is a compile error |
| V1b | parsePluginManifest / loadPluginManifest given text that opens with one byte order mark (U+FEFF) | Loads as without it. Two of them, or one after the first character, is a manifest parse error saying where |
| V2 | Two plugins declare the same effect id | startup error |
| V3 | Two plugins declare the same extKind | startup error |
| V3a | One plugin declares the same effect id or extKind id twice, whatever the two entries say | startup error |
| V4 | Declaring a central reservation (core:foo) | startup error |
| V5 | type: effects declares framework:foo:bar | startup error |
| V6 | Plugin extraction returns an undeclared effect id (strict mode) | extraction error |
| V6a | A plugin's classify calls ctx.registry.assertEffectDeclared for an id no manifest declares | the run ends with exit 3, as for V6, though the error is the registry's rather than the core's — under aburi scan --discover too |
| V7 | Plugin extraction returns an undeclared extKind (strict mode) | extraction error |
| V8 | name: stripe declares the x-acme: prefix | manifest validation error |
| V9 | Loading the same manifest twice | idempotent |
| V10 | Emitting x-acme:anything at extraction time under a declared effectPrefixes: ["x-acme"] | passes |
| V11 | A declares extKinds[].id: "framework:acme:job", B declares extKindPrefixes: ["framework:acme"] | startup error (subsumption conflict) |
| V11a | One plugin declares two extKind prefixes or two derivedBy prefixes where one contains the other (fp:pipe and fp:pipe:async) | startup error. The same prefix written twice in one list is refused earlier, by the schema's uniqueItems; register itself leaves an exact repeat alone, since it cannot give a lookup two owners |
| V12 | Emitting undeclared values under aburi scan --discover | warning only; recorded in aburi-vocab-discovered.json |
| V13 | Treating @Foo as a boundary via Framework hints (§11.3) alone | OK; no plugin manifest required |
| V13a | Two lang manifests declare the same languageId; a lang manifest declares none, one outside [a-z][a-z0-9]*, or slice; an effects or framework manifest declares one | startup error naming the plugin (and, for a duplicate, the plugin that declared it first) |
| V14 | aburi scan with a plugin listed in aburi.json whose manifest the registry refuses at startup (§6.1–§6.2), for any of the refusals cli-spec.md CL49 lists | exit 3 before extraction, stderr naming the config entry that loaded the plugin ahead of the registry's reason |
9.5 Manifest schema compatibility policy
aburi.plugin.v1.json adopts the same compatibility policy as the IR schema (ir-schema.md §15):
| Change | Compatibility |
|---|---|
| Adding a required field | Breaking (to v2) |
| Adding an optional field | Non-breaking |
| Adding an enum value (to the extent consumers tolerate unknowns) | Non-breaking |
| Removing an enum value | Breaking |
| Tightening a pattern | Breaking |
| Loosening a pattern | Non-breaking |
| Adding an array uniqueness constraint | Breaking |
languageId shows how a field one type needs is added within v1: the schema lists it as optional and the registry requires it of type: lang. Requiring it in the schema would make every lang manifest written before it invalid, which the table above counts as breaking.
Since consumers may treat unknown values of the type enum (lang / effects / framework) as errors, additions to it are also treated as breaking.
10. Design decisions
10.1 Abolishing "official vs third-party"
Aburi cannot tell whether a plugin is published on npm or local to a repository. Ownership determination is unified on manifest declarations.
10.2 IR files themselves may contain undeclared values
An IR consumer (e.g. running the Markdown renderer in a different environment) may not have the plugins used at generation time. The registry guard applies only at generation time; an IR file is valid as long as it satisfies the schema patterns.
10.3 Why central reservations are hardcoded
If the reservation list could be changed dynamically via config, an IR generated at one point in time could be judged a "reservation conflict" in a different environment. Each Aburi version carries a fixed reservation list.
10.4 Why prefix ownership is allowed
For in-house frameworks and experimental plugins, where the vocab changes frequently or is large, forcing individual enumeration would break the development loop. Prefix ownership lets a plugin assert only "ownership of the namespace" and leaves the contents to runtime, providing flexibility.
10.5 Purpose of derivedByPrefixes
derivedBy[] is a string that lets IR consumers know which plugin made a given determination. Registering prefixes in the registry lets the Markdown renderer control display, e.g. rendering framework:nestjs:* derivedBy entries as "NestJS plugin".
11. Support for minor languages and custom plugins
There are three tiers, by complexity, for bringing a new language / in-house framework / one-off custom rule into Aburi.
11.1 Tier 1: Published plugin
- Published on npm,
type: lang | effects | framework - Vocab should be individually enumerated as a rule (discoverability, documentation value)
- Examples:
@aburi/effects-nest,@aburi/lang-typescript
11.2 Tier 2: Project plugin
- Local code inside the repository (e.g.
aburi-plugins/internal-framework.mjs) - Referenced via a
package.jsonworkspace or a direct path in the config - The manifest format is exactly the same as Tier 1
- Vocab may use prefix ownership (§3.3)
- Example:
{
"$schema": "https://aburi.dev/schema/aburi.plugin.v1.json",
"name": "acme-framework",
"version": "0.0.1",
"type": "framework",
"engines": { "aburi": "^1.0.0" },
"provides": {
"effects": [],
"effectPrefixes": [],
"extKinds": [],
"extKindPrefixes": ["framework:acme"],
"derivedByPrefixes": ["framework:acme"],
"frameworks": ["acme-framework"]
}
}It may freely emit framework:acme:controller / framework:acme:job / framework:acme:saga etc. at runtime.
11.3 Tier 3: Framework hints (no code required)
- Declarations inside
aburi.jsononly; no code whatsoever - Covers needs like "treat
@MyDecoratoras a boundary" or "treatclass *Handlerasframework:mycorp:handler" - Specified in
config.md; this document only shows the hook point - A user-written
extKind: "framework:acme:controller"is automatically converted internally toframework:hint:acme:controller(details inconfig.md§8.3.1). By transparently insertinghint:as the second segment, the core avoids namespace conflicts with an existing official npmframework-acmeplugin - A user directly entering
extKind: "framework:hint:*"is a config validation error (rejected byconfig-check.mjs) - The whole of
framework:hint:*is a centrally reserved namespace (§5.1); third-party npm plugins may not declare it - Sketch:
{
"frameworkHints": [
{
"name": "acme-framework",
"decorators": {
"AcmeController": { "boundary": true, "extKind": "framework:acme:controller" },
"AcmeJob": { "boundary": true, "extKind": "framework:acme:job" }
},
"classNamePatterns": {
"*Handler": { "extKind": "framework:acme:handler" }
}
}
]
}Aburi core treats this internally as an ad-hoc plugin and auto-registers the framework:hint:acme:* vocab. No code extraction logic is required. The reservation in §5.1 is what keeps that namespace for hints: the registry admits a namespace under framework:hint only from the manifests it synthesizes, and a hint still cannot claim framework:hint itself or any other reserved root. The ad-hoc plugin runs after every plugin in frameworks (config.md §8.3.2).
11.4 Choosing a tier
| Situation | Recommended tier |
|---|---|
| A published language / framework in wide use | Tier 1 |
| An in-house / project-specific framework that needs effect-detection logic | Tier 2 |
Only simple classification, e.g. treating @MyDecorator as a boundary | Tier 3 |
| Supporting a minor language (Crystal/Zig etc.) | Tier 1 or Tier 2 (tree-sitter grammar + extraction logic required) |
| Plugin under iterative development, vocab not yet settled | Tier 2 + --discover (§11.5) |
11.5 For development iteration: --discover mode
aburi scan --discover- Even when plugin extraction emits values not declared in the registry, this is not an error: a warning is issued and the value is recorded in
.aburi/aburi-vocab-discovered.json - The developer inspects the record and decides whether to promote entries into the manifest
- The CI default is strict (no
--discover); discover is recommended for local development only
11.5.1 aburi-vocab-discovered.json format
{
"discoveredAt": "2026-06-21T15:30:00Z", // absent under --no-timestamp
"items": [
{
"kind": "effect", // "effect" | "extKind"
"value": "x-prisma:bulk-delete",
"firstSeenBy": "effects-prisma", // the plugin that first generated this value
"alsoSeenBy": [], // other plugins that generated the same value in the same run (rare)
"occurrences": 3, // how many times the run emitted it
"samples": [ // the first 3 occurrences
{ "file": "apps/billing/src/x.ts", "line": 42, "symbol": "ts:apps/billing/src/x.ts#foo" } // no line for an extKind
]
}
]
}firstSeenBy: when multiple plugins generate the same undeclared value in one run, the first plugin owns italsoSeenBy: subsequent plugins are downgraded to warnings and appended to the recordoccurrences: every emission of the value in the run, whichever plugin emitted it- Items are in the order the scan first met them, which is path order, so the same workspace gives the same record
- There is no
$schemakey until the schema for this file exists, and noframeworkkind: a framework name is not checked against the manifests
This makes it mechanically decidable at promote time which plugin's manifest an entry should be added to.
11.6 Minimal manifest example for a minor-language plugin
If lang-crystal were hypothetically written, it could get by on the core vocabulary alone without adding any vocab:
{
"$schema": "https://aburi.dev/schema/aburi.plugin.v1.json",
"name": "lang-crystal",
"version": "0.1.0",
"type": "lang",
"languageId": "cr",
"engines": { "aburi": "^1.0.0" },
"provides": {
"effects": [],
"effectPrefixes": [],
"extKinds": [],
"extKindPrefixes": [],
"derivedByPrefixes": ["lang:crystal"],
"frameworks": []
}
}It simply projects Crystal's class / module / def onto the IR core enum (class / module / function) without using extKind. The vocab declaration burden is near zero.
When special concepts (fp:macro, oop:abstract, etc.) become desirable, add the corresponding prefix to extKindPrefixes. Extension can be gradual.