vigiles 30.0.1 → 31.0.0

package/dist/core/compile.js

@@ -169,7 +169,7 @@ function validateCommandRef(command, basePath) {
     }
     return null;
 }
-function validateSymbolRef(file, name, basePath) {
+async function validateSymbolRef(file, name, basePath) {
     const full = (0, node_path_1.resolve)(basePath, file);
     if (!(0, node_fs_1.existsSync)(full)) {
         return {
@@ -178,7 +178,7 @@ function validateSymbolRef(file, name, basePath) {
             path: file,
         };
     }
-    const support = (0, symbols_js_1.langForFile)(file);
+    const support = await (0, symbols_js_1.langForFile)(file);
     if (support.kind === "unsupported") {
         return {
             type: "stale-ref",
@@ -186,16 +186,16 @@ function validateSymbolRef(file, name, basePath) {
             path: file,
         };
     }
-    if (support.kind === "grammar-missing") {
-        // The language is parseable by this tool; the optional grammar is absent in THIS install.
+    if (support.kind === "grammar-load-failed") {
+        // The language is parseable by this tool; its grammar failed to load in THIS process.
         // Distinct wording on purpose — see the union's docblock in core/symbols.ts.
         return {
             type: "stale-ref",
-            message: `Symbol not checked: the ${support.id} grammar is not installed (npm i -D ${support.pkg})`,
+            message: (0, symbols_js_1.notCheckedReason)(support),
             path: file,
         };
     }
-    if (!(0, symbols_js_1.fileDefinesSymbol)(full, name)) {
+    if (!(await (0, symbols_js_1.fileDefinesSymbol)(full, name))) {
         return {
             type: "stale-ref",
             message: `"${name}" is not defined in ${file}`,
@@ -235,18 +235,18 @@ function validateGlobRef(pattern, basePath) {
     }
     return null;
 }
-function validateRefs(fragments, basePath) {
+async function validateRefs(fragments, basePath) {
     const errors = [];
     for (const fragment of fragments) {
         if (typeof fragment !== "string") {
-            errors.push(...validateOneRef(fragment, basePath));
+            errors.push(...(await validateOneRef(fragment, basePath)));
         }
     }
     return errors;
 }
 const wrap = (e) => (e ? [e] : []);
 /** Validate a single non-string fragment (a `Ref` or `EffectRegion`). */
-function validateOneRef(r, basePath) {
+async function validateOneRef(r, basePath) {
     switch (r._ref) {
         case "file":
             return wrap(validateFileRef(r.path, basePath));
@@ -263,7 +263,7 @@ function validateOneRef(r, basePath) {
                 ]
                 : [];
         case "symbol":
-            return wrap(validateSymbolRef(r.file, r.symbol, basePath));
+            return wrap(await validateSymbolRef(r.file, r.symbol, basePath));
         case "dir":
             return wrap(validateDirRef(r.path, basePath));
         case "glob":
@@ -448,7 +448,7 @@ const RESERVED_SECTION_KEYS = new Set([
     "key_files",
     "rules",
 ]);
-function compileSectionsSection(spec, basePath, maxSectionLines) {
+async function compileSectionsSection(spec, basePath, maxSectionLines) {
     if (!spec.sections)
         return { lines: [], errors: [] };
     const lines = [];
@@ -467,7 +467,7 @@ function compileSectionsSection(spec, basePath, maxSectionLines) {
             lines.push(`## ${heading}\n\n${content.trim()}`);
         }
         else {
-            errors.push(...validateRefs(content, basePath));
+            errors.push(...(await validateRefs(content, basePath)));
             const rendered = content.map(renderFragment).join("");
             errors.push(...validateSectionContent(name, rendered, maxSectionLines));
             lines.push(`## ${heading}\n\n${rendered.trim()}`);
@@ -581,7 +581,7 @@ function compileRulesSection(spec, basePath, options) {
 // (no frontmatter), so Codex/OpenCode reuse it unchanged — only the h1 target
 // differs, which already comes from the injected dialect. Nothing here is
 // CC-only, so there is no per-dialect branch to gate.
-function compileClaude(spec, options = {}) {
+async function compileClaude(spec, options = {}) {
     const targets = spec.target ?? options.dialect?.instructionTargets[0] ?? DEFAULT_TARGET;
     const target = Array.isArray(targets) ? targets[0] : targets;
     const basePath = options.basePath ?? process.cwd();
@@ -614,7 +614,7 @@ function compileClaude(spec, options = {}) {
     }
     // Per-spec maxSectionLines takes precedence, then compile options
     const maxSectionLines = spec.maxSectionLines ?? options.maxSectionLines;
-    const prose = compileSectionsSection(spec, basePath, maxSectionLines);
+    const prose = await compileSectionsSection(spec, basePath, maxSectionLines);
     const keyFiles = compileKeyFilesSection(spec, basePath);
     const commands = compileCommandsSection(spec, basePath);
     const rules = compileRulesSection(spec, basePath, options);
@@ -902,7 +902,7 @@ function checkInlineCode(markdown, max) {
 /**
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
  */
-function compileSkill(spec, options = {}) {
+async function compileSkill(spec, options = {}) {
     // 🔴 NORMALISE FIRST, before anything reads the spec. `compileSkill` accepts a
     // `SkillSpec` STRUCTURALLY, so a caller can hand us `{ _specType: "skill", …,
     // result: cmd(…) }` without ever touching `experimental_skill()`. Both readers
@@ -931,7 +931,7 @@ function compileSkill(spec, options = {}) {
             });
         }
     }
-    errors.push(...validateRefs(collectSkillRefs(spec), basePath));
+    errors.push(...(await validateRefs(collectSkillRefs(spec), basePath)));
     // A typed `output` Result contract is valid ONLY for a forked skill: an inline
     // skill has no call→return boundary, so a typed outcome there is a category
     // error (see research/spec-syntax-and-railway-scope.md). Enforce it at compile.
@@ -1063,7 +1063,7 @@ function purityMarker(purity) {
     return `<!-- vigiles:purity:${level} -->`;
 }
 /** Render the subagent's named `##` system-prompt sections (verified like CLAUDE.md). */
-function renderAgentSections(sections, basePath) {
+async function renderAgentSections(sections, basePath) {
     const lines = [];
     const errors = [];
     for (const [name, content] of Object.entries(sections)) {
@@ -1079,7 +1079,7 @@ function renderAgentSections(sections, basePath) {
             lines.push(`## ${heading}\n\n${content.trim()}`);
         }
         else {
-            errors.push(...validateRefs(content, basePath));
+            errors.push(...(await validateRefs(content, basePath)));
             const rendered = content.map(renderFragment).join("");
             errors.push(...validateSectionContent(name, rendered));
             lines.push(`## ${heading}\n\n${rendered.trim()}`);
@@ -1134,7 +1134,7 @@ function renderAgentRules(rules) {
  * Verifies the tool contract and the body's references; the marks the body
  * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
-function compileAgent(spec, options) {
+async function compileAgent(spec, options) {
     const basePath = options.basePath ?? process.cwd();
     const specFile = options.specFile ?? "agent.md.spec.ts";
     const dialect = options.dialect;
@@ -1169,13 +1169,13 @@ function compileAgent(spec, options) {
         }
     }
     if (Array.isArray(spec.body)) {
-        errors.push(...validateRefs(spec.body, basePath));
+        errors.push(...(await validateRefs(spec.body, basePath)));
     }
     const sections = [];
     if (spec.body !== undefined)
         sections.push(renderBody(spec.body).trim());
     if (spec.sections) {
-        const result = renderAgentSections(spec.sections, basePath);
+        const result = await renderAgentSections(spec.sections, basePath);
         sections.push(...result.lines);
         errors.push(...result.errors);
     }
@@ -1287,7 +1287,7 @@ function checkFileHash(filePath) {
  * Compare a generated file against what the spec would produce.
  * Returns the diff so users can see what was manually changed.
  */
-function adoptDiff(filePath, spec, basePath, dialect) {
+async function adoptDiff(filePath, spec, basePath, dialect) {
     const fullPath = (0, node_path_1.resolve)(basePath, filePath);
     const currentContent = (0, node_fs_1.existsSync)(fullPath)
         ? (0, node_fs_1.readFileSync)(fullPath, "utf-8")
@@ -1296,7 +1296,7 @@ function adoptDiff(filePath, spec, basePath, dialect) {
     // Compile the spec to get what it WOULD produce
     let compiledContent = null;
     if (spec._specType === "claude") {
-        const { markdown } = compileClaude(spec, {
+        const { markdown } = await compileClaude(spec, {
             basePath,
             specFile: filePath,
             dialect,
@@ -1304,11 +1304,14 @@ function adoptDiff(filePath, spec, basePath, dialect) {
         compiledContent = markdown;
     }
     else if (spec._specType === "skill") {
-        const { markdown } = compileSkill(spec, { basePath, specFile: filePath });
+        const { markdown } = await compileSkill(spec, {
+            basePath,
+            specFile: filePath,
+        });
         compiledContent = markdown;
     }
     else if (spec._specType === "agent") {
-        const { markdown } = compileAgent(spec, {
+        const { markdown } = await compileAgent(spec, {
             basePath,
             specFile: filePath,
             dialect,

package/dist/core/config-schema.d.ts

@@ -69,20 +69,20 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         checkboxes: "checkboxes";
     }>>>;
     rules: z.ZodPrefault<z.ZodObject<{
-        "spec-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "orphan-docs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "duplicate-rules": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "require-instructions-spec": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "require-skill-spec": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        integrity: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        coverage: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+        "spec-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "orphan-docs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "duplicate-rules": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "require-instructions-spec": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "require-skill-spec": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        integrity: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        coverage: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
             linterRules: z.ZodOptional<z.ZodNumber>;
             scripts: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
             linterRules: z.ZodOptional<z.ZodNumber>;
             scripts: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>], null>]>>;
-        "untested-skill": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+        "untested-skill": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
             include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             testExtension: z.ZodOptional<z.ZodString>;
@@ -91,7 +91,7 @@ export declare const vigilesConfigSchema: z.ZodObject<{
             exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             testExtension: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], null>]>>;
-        "untested-subagent": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+        "untested-subagent": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
             include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             testExtension: z.ZodOptional<z.ZodString>;
@@ -100,7 +100,7 @@ export declare const vigilesConfigSchema: z.ZodObject<{
             exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             testExtension: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], null>]>>;
-        "untested-hook": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+        "untested-hook": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
             include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             testExtension: z.ZodOptional<z.ZodString>;
@@ -109,28 +109,28 @@ export declare const vigilesConfigSchema: z.ZodObject<{
             exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
             testExtension: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], null>]>>;
-        "unmarked-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "subagent-tool-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "hook-events": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "subagent-frontmatter": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "mcp-config": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "skill-frontmatter": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "mcp-tool-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "hook-script-exists": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "prefer-compiled-hooks": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "disallowed-tools-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "description-overlap": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "skill-description-budget": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "frontmatter-valid": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "mcp-hook-target-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "lethal-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "skill-resource-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "skill-missing-fence": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "plugin-dir-layout": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "delegation-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "hook-block-ineffective": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "hook-matcher": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
-        "doc-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "off" | "warn" | "error">>>;
+        "unmarked-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "subagent-tool-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "hook-events": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "subagent-frontmatter": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "mcp-config": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "skill-frontmatter": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "mcp-tool-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "hook-script-exists": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "prefer-compiled-hooks": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "disallowed-tools-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "description-overlap": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "skill-description-budget": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "frontmatter-valid": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "mcp-hook-target-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "lethal-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "skill-resource-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "skill-missing-fence": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "plugin-dir-layout": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "delegation-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "hook-block-ineffective": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "hook-matcher": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
+        "doc-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
     }, z.core.$strict>>;
     files: z.ZodDefault<z.ZodArray<z.ZodString>>;
     maxRules: z.ZodOptional<z.ZodNumber>;

package/dist/core/refs.d.ts

@@ -26,7 +26,7 @@ export declare function symbolRefs(markdown: string): SymbolRef[];
  * file must exist and define the named symbol. `basePath` is the directory the
  * paths resolve against (the instruction file's own directory).
  */
-export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
+export declare function verifySymbolRefs(markdown: string, basePath: string): Promise<SymbolRefError[]>;
 /**
  * Whether a span is a **linter-rule reference** that ought to be marked
  * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the lint can verify the
@@ -50,7 +50,7 @@ export declare function unmarkedCodeRefs(markdown: string): Span[];
  * code-shaped span that ought to be a mark. The shared detector behind both the
  * `vigiles refs` CLI and the PostToolUse refs-hook.
  */
-export declare function collectRefIssues(markdown: string, basePath: string): string[];
+export declare function collectRefIssues(markdown: string, basePath: string): Promise<string[]>;
 /** What the refs-hook should do given the issue count and configured severity. */
 export type RefsHookAction = "ok" | "nudge" | "block";
 /**

package/dist/core/refs.js

@@ -70,11 +70,11 @@ function symbolRefs(markdown) {
  * file must exist and define the named symbol. `basePath` is the directory the
  * paths resolve against (the instruction file's own directory).
  */
-function verifySymbolRefs(markdown, basePath) {
+async function verifySymbolRefs(markdown, basePath) {
     const errors = [];
     for (const ref of symbolRefs(markdown)) {
         const full = (0, node_path_1.resolve)(basePath, ref.file);
-        const support = (0, symbols_js_1.langForFile)(ref.file);
+        const support = await (0, symbols_js_1.langForFile)(ref.file);
         if (!(0, node_fs_1.existsSync)(full)) {
             errors.push({ ...ref, reason: `File not found: "${ref.file}"` });
         }
@@ -84,15 +84,12 @@ function verifySymbolRefs(markdown, basePath) {
                 reason: `Unsupported language for symbol check: "${ref.file}"`,
             });
         }
-        else if (support.kind === "grammar-missing") {
-            // NOT "unsupported": the language is one this tool parses, the optional grammar just is
-            // not installed here. Saying it the other way would report an un-run check as a verdict.
-            errors.push({
-                ...ref,
-                reason: `Symbol not checked: the ${support.id} grammar is not installed (npm i -D ${support.pkg})`,
-            });
+        else if (support.kind === "grammar-load-failed") {
+            // NOT "unsupported" and NOT "not defined": the language is one this tool parses, its
+            // grammar failed to load here. Either other wording would report an un-run check as a verdict.
+            errors.push({ ...ref, reason: (0, symbols_js_1.notCheckedReason)(support) });
         }
-        else if (!(0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol)) {
+        else if (!(await (0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol))) {
             errors.push({
                 ...ref,
                 reason: `"${ref.symbol}" is not defined in ${ref.file}`,
@@ -149,9 +146,9 @@ function unmarkedCodeRefs(markdown) {
  * code-shaped span that ought to be a mark. The shared detector behind both the
  * `vigiles refs` CLI and the PostToolUse refs-hook.
  */
-function collectRefIssues(markdown, basePath) {
+async function collectRefIssues(markdown, basePath) {
     const out = [];
-    for (const b of verifySymbolRefs(markdown, basePath)) {
+    for (const b of await verifySymbolRefs(markdown, basePath)) {
         out.push(`line ${String(b.line)}: ${b.reason}`);
     }
     for (const u of unmarkedCodeRefs(markdown)) {

package/dist/core/spec.js

@@ -1,4 +1,9 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles/spec` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-spec.api.md`, which
+// `npm run api:check` fails on.
 /**
  * vigiles v2 — Executable specification system.
  *

package/dist/core/symbols.d.ts

@@ -1,30 +1,33 @@
 import { Lang } from "@ast-grep/napi";
-/** Which optional grammars this process actually has. Exported so a report can say so. */
-export declare function installedGrammars(): ReadonlySet<string>;
-/** A language key accepted by ast-grep's `parse` (core enum or registered id). */
-type LangKey = Lang | string;
+import { type WasmLang } from "./tree-sitter-wasm.js";
+/** A language key: an `@ast-grep/napi` built-in, or one of the WASM grammars. */
+type LangKey = Lang | WasmLang;
 /**
  * Whether this file's language can be parsed HERE, and if not, which of the two reasons.
  *
- * 🔴 THE THREE CASES ARE SEPARATE MEMBERS BECAUSE THEY ARE SEPARATE FACTS. The previous
- * signature was `LangKey | null`, where `null` meant "extension not in the table" and callers
- * printed "Unsupported language for symbol check". Making the grammars optional would have
- * given that same `null` a second meaning — "the language IS ours, the package is simply not
- * installed" — and both callers would have kept printing the first sentence. That is the
- * failure this codebase exists to catch: a check that did not run, reported in the words of a
- * check that did. A union makes the compiler demand the distinction at every call site.
+ * 🔴 THE THREE CASES ARE SEPARATE MEMBERS BECAUSE THEY ARE SEPARATE FACTS. "Extension not in
+ * the table" and "the language IS ours but its grammar failed to load in this process" must not
+ * share one `null`: both callers would print the first sentence, and a check that did not run
+ * would read as a verdict. With WASM grammars shipped as a regular dependency there is no
+ * install or platform gap left, so `grammar-load-failed` should not happen — but if the runtime
+ * genuinely cannot load, the report carries the loader's own error text, never "not defined"
+ * and never an install instruction the user cannot act on.
  */
 export type LangSupport = {
     readonly kind: "ready";
     readonly lang: LangKey;
 } | {
-    readonly kind: "grammar-missing";
-    readonly id: string;
-    readonly pkg: string;
+    readonly kind: "grammar-load-failed";
+    readonly lang: WasmLang;
+    readonly error: string;
 } | {
     readonly kind: "unsupported";
 };
-export declare function langForFile(file: string): LangSupport;
+export declare function langForFile(file: string): Promise<LangSupport>;
+/** The one sentence both callers print for a symbol reference that could not be checked. */
+export declare function notCheckedReason(support: Extract<LangSupport, {
+    kind: "grammar-load-failed";
+}>): string;
 /** A symbol definition found in a file. */
 export interface SymbolDef {
     /** The defined identifier, e.g. "parseConfig". */
@@ -36,10 +39,13 @@ export interface SymbolDef {
     /** 1-based line of the definition. */
     readonly line: number;
 }
-/** Extract the symbols defined in a single file's source. */
-export declare function definedSymbols(code: string, lang: LangKey): SymbolDef[];
+/**
+ * Extract the symbols defined in a single file's source. Async because the Python / Ruby / Rust
+ * grammars are WebAssembly, whose instantiation is async; the napi languages resolve at once.
+ */
+export declare function definedSymbols(code: string, lang: LangKey): Promise<SymbolDef[]>;
 /** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
-export declare function definedSymbolsInFile(file: string): SymbolDef[];
+export declare function definedSymbolsInFile(file: string): Promise<SymbolDef[]>;
 /**
  * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
  * the whole check for a file-qualified reference (`path#symbol`): we parse the
@@ -47,6 +53,6 @@ export declare function definedSymbolsInFile(file: string): SymbolDef[];
  * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
  * typed dynamic symbols resolve without running Sorbet / the TS compiler.
  */
-export declare function fileDefinesSymbol(file: string, name: string): boolean;
+export declare function fileDefinesSymbol(file: string, name: string): Promise<boolean>;
 export {};
 //# sourceMappingURL=symbols.d.ts.map