any-doctor 0.1.2 → 0.2.0

package/CONTEXT.md

@@ -163,6 +163,51 @@ The interface shared by doctor programs, the runner, the report, the
 fixture harness, and the generator prompt. The single place where the
 shape of ctx, meta, findings, and the runner protocol is defined.
 
+## Doctor SDK
+
+The deeper semantic portion of the DoctorCtx interface: host-owned queries for
+identity, value disposition, resource lifetime and option presence. It hides the
+parser/scope/type adapters and returns bounded evidence plus an explicit known or
+unknown result. It is not initially an importable package; Confinement still gives
+doctor programs one route to product capabilities through `ctx`. See the
+[Doctor SDK design](docs/plans/doctor-sdk/design.md).
+
+## Semantic result
+
+The answer from one Doctor SDK query: a known value with supporting evidence, or
+an unknown result with a named reason. Unknown never means absent, discarded,
+unreleased or safe. A check that cannot support its claim from a known result
+abstains and exposes narrowed coverage.
+
+## Value Path
+
+A bounded Doctor SDK query that establishes whether one static property path is
+present or absent at one source observation. A present result identifies the
+terminal expression and may include a primitive constant. Unsupported flow is
+unknown; it never implies absence or safety.
+
+## Check recipe
+
+A host-owned composition of Doctor SDK queries for a recurring check family, such
+as an unhandled value, a resource without release, or a required/recommended call
+option. The recipe owns recurring mechanics, uncertainty, evidence and challenge
+selection; the doctor owns technology-specific selectors, meaning and copy.
+
+Each maintained recipe is locally complete under `src/recipes/`: its module owns
+the host kind and implied needs, wire-query parser, semantic composition,
+authoring catalog entry and generated challenge profile. `recipe-definitions.ts`
+is the one registry consumed by the host, SDK, authoring catalog and certifier.
+Adding or changing a recipe happens in its recipe module rather than by editing
+parallel switches in those consumers.
+
+## Challenge profile
+
+A maintained certification corpus selected by a check recipe or declared semantic
+capability. It pairs genuine positives with lookalikes, shadowing, aliases,
+transfers, unknown cases, positive neighbors, unavailable analysis and exact
+occurrence witnesses. It supplements author fixtures and independent evaluation;
+it does not replace either.
+
 ## DoctorCtx (ctx)
 
 The capability boundary a doctor program is expected to use: read-only,
@@ -174,16 +219,28 @@ writes, no subprocesses, no network.
 (test-named code files — `*.test.*`/`*.spec.*` with a code extension —
 and `test/`, `tests/`, `__tests__/` directories): tests mimic production
 shapes without being production reads. The one law (`isTestPath`) and
-the one derivation (`includeTestsFor`) live in contract.ts; every read
-capability applies them. A Doctor run opts back in with
+the one derivation (`includeTestsFor`) live in contract.ts; diagnostic
+inventory and search apply them. Reference evidence includes tests. A Doctor run opts back in with
 `--include-tests`; `ctx.files.read()` is never filtered — an explicit
 path is a deliberate choice. `ctx.files.readMasked()` is the one
 masking implementation (comments and strings blanked, offsets and
 length preserved — a masked position addresses the same char in the
 source); doctors carry no private copies — the bundled pack's remaining
-copies migrate on the recorded triggers. Verify always sees everything
-its fixtures seed: the sandbox is the doctor's own world, and a seed
-named `*.test.ts` is deliberate test data.
+copies migrate on the recorded triggers. Verify defaults to the deliberately seeded
+test scope; fixtures can also exercise ordinary diagnostic defaults.
+See [project consumer facts](docs/project-consumer-analysis.md) for the interfaces.
+
+## Diagnostic scope
+
+The authorized files eligible for findings in a run. Tests are opt-in and generated
+modules are omitted; this scope is distinct from the evidence used to analyze them.
+
+## Consumer evidence
+
+An observed reference, declaration dependency, public exposure, or uncertainty
+associated with an exported binding by module identity. Test and generated modules
+may supply this evidence without becoming diagnostic targets; absence within
+supported coverage is a review candidate, never deletion authorization.
 
 ## Rule query
 
@@ -217,8 +274,9 @@ the analysis they need on their CheckMeta (`needs` — vocabulary:
 and the report renders "narrowed" — a degraded run is visible, never
 silent. `ctx.analysis.calls(file)` provides immediate call use, receiver identity,
 inline callback registration, and linked call ranges. These are syntax facts;
-stored, passed, or returned is not a promise-settlement verdict. Parse/adapter
-errors fail the doctor run explicitly. References answer by position, so analysis queries compose with
+stored, passed, or returned is not a promise-settlement verdict. A parse or
+adapter error narrows the affected file while analyzable neighboring files
+continue; the partial scan receives no score or grade. References answer by position, so analysis queries compose with
 rule queries: shapes from one engine, identities from the other.
 
 ## Engine

package/README.md

@@ -46,6 +46,7 @@ Non-terminals and CI never see a prompt — output is stable and pipeable
 | **convex** | Convex discipline: indexed reads, bounded collects, validated args, awaited writes, honest runtime boundaries | 15 |
 | **effect-v4-kitlangton** | Effect v4 discipline — the mechanical rules of the [kitlangton Effect skill](https://www.ui-skills.com/skills/kitlangton/effect), enforced | 10 |
 | **openrouter** | OpenRouter discipline: stream errors surfaced, keep-alives skipped, cancellations that stop billing | 5 |
+| **deepgram** | Deepgram discipline: endpoint/model compatibility, streaming options, Read shapes, hosts, and proven browser key exposure | 5 |
 | **async** | Async and concurrency: dropped promise results, uncleared timers, fetch hygiene | 3 |
 
 Checks ship positive and innocent-lookalike fixtures. `verify` compares an
@@ -123,6 +124,9 @@ npx any-doctor@latest run --all --fail-on warning --base origin/main
 
 ## Docs
 
+- [Doctor SDK semantic queries and recipes](docs/doctor-sdk.md) — confined,
+  evidence-bearing analysis and automatic recipe challenge profiles
+
 | Doc | What it holds |
 |---|---|
 | [skill/any-doctor.skill.md](skill/any-doctor.skill.md) | The authoring contract — what your agent reads to write doctors |

package/bin/analysis-host.d.ts

@@ -1,4 +1,6 @@
-import { AnalysisFile, AnalysisSpans, AnalysisCalls, Mode } from "./contract.js";
+import { ProjectConsumers } from "./project-consumers.js";
+import { FunctionStructure } from "./function-structure.js";
+import { AnalysisFile, AnalysisSpans, AnalysisCalls, IdentityValue, Mode, OptionPresence, RecipeDecision, ResourceLifetime, SemanticResult, SourceRange, ValueDisposition, ValuePathValue } from "./contract.js";
 import { analysisStatus, analyzeBindings, analyzeSpans, analyzeCalls } from "./analysis.js";
 type Analyzer = typeof analyzeBindings;
 type SpansAnalyzer = typeof analyzeSpans;
@@ -8,16 +10,33 @@ export interface AnalysisRequestBody {
     kind?: unknown;
     file?: unknown;
     root?: unknown;
+    sourceDigest?: unknown;
+    expression?: unknown;
+    query?: unknown;
 }
 export type AnalysisResponse = {
+    project: ProjectConsumers;
+} | {
+    structures: FunctionStructure[];
+} | {
     available: boolean;
     reason?: string;
+    provider?: import("./contract.js").SemanticProviderProvenance;
 } | {
     file: AnalysisFile;
 } | {
     file: AnalysisSpans;
 } | {
     file: AnalysisCalls;
+} | {
+    semantic: SemanticResult<IdentityValue | {
+        matches: boolean;
+    } | ValuePathValue | ValueDisposition | ResourceLifetime | OptionPresence | RecipeDecision>;
+    execution?: {
+        modelRequests: number;
+        modelCacheHits: number;
+    };
+    subject?: SourceRange;
 } | {
     error: string;
 };

package/bin/analysis-host.js

@@ -1,22 +1,50 @@
+import { createHash } from "node:crypto";
+import { projectConsumers } from "./project-consumers.js";
+import { functionStructures } from "./function-structure.js";
 import * as fs from "fs";
 import * as path from "path";
-import { searchBase, withinBase, withinDir } from "./contract.js";
-import { analysisStatus, analyzeBindings, analyzeSpans, analyzeCalls } from "./analysis.js";
+import { searchBase, SEMANTIC_RESULT_VERSION, withinBase, withinDir } from "./contract.js";
+import { analysisStatus, analyzeBindings, analyzeSpans, analyzeCalls, semanticProviderProvenance } from "./analysis.js";
+import { callIdentityResult, identityResult, optionPresenceResult, recipeEvaluationRuntime, resourceLifetimeResult, valueAtPathResult, valueDispositionResult } from "./doctor-sdk.js";
+import { RECIPE_DEFINITIONS } from "./recipe-definitions.js";
+import { parseIdentityQuery, parseOptionQuery } from "./semantic-query-parsers.js";
 // One cache per host process. The host lives in the runner process, so
 // the lifetime is the any-doctor invocation; across a cohort's doctors
 // the same unchanged file answers from memory.
 const modelCache = new Map();
 const callsCache = new Map();
 const spansCache = new Map();
-// Test seam: the model cache is keyed by mtime+size for the process
+// Test seam: the model cache is keyed by content digest for the process
 // lifetime; tests bust it between cases. Invisible to slop's
-// default run (test-file consumers are the documented narrowing).
+// default run. Consumer graphs include test evidence independently.
 export function clearAnalysisCache() {
     modelCache.clear();
     spansCache.clear();
     callsCache.clear();
 }
+// Pair parsing with evaluation so each semantic kind has one typed owner.
+function semanticHandler(parse, evaluate) {
+    return (value) => {
+        const query = parse(value);
+        return query === null ? null : (file, source, facts, expression) => evaluate(file, source, facts, expression, query);
+    };
+}
+const recipeSemanticHandlers = {};
+for (const candidate of Object.values(RECIPE_DEFINITIONS)) {
+    const definition = candidate;
+    recipeSemanticHandlers[definition.kind] = semanticHandler(definition.parse, (file, source, facts, expression, query) => definition.evaluate(recipeEvaluationRuntime, file, source, facts, expression, query));
+}
+const semanticHandlers = {
+    "call-identity": semanticHandler(parseIdentityQuery, callIdentityResult),
+    identity: semanticHandler(parseIdentityQuery, identityResult),
+    "value-path": semanticHandler(parseValuePathQuery, valueAtPathResult),
+    "value-disposition": semanticHandler(parseDispositionQuery, valueDispositionResult),
+    "resource-lifetime": semanticHandler(parseResourceQuery, resourceLifetimeResult),
+    "option-presence": semanticHandler(parseOptionQuery, optionPresenceResult),
+    ...recipeSemanticHandlers,
+};
 export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, status = analysisStatus, spansAnalyzer = analyzeSpans, callsAnalyzer = analyzeCalls) {
+    var _a;
     const base = searchBase(mode);
     const root = typeof req.root === "string" ? path.resolve(req.root) : "";
     if (base === "" || !withinBase(root, base)) {
@@ -24,9 +52,56 @@ export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, sta
     }
     if (req.kind === "available") {
         const s = status();
-        return s.available ? { available: true } : { available: false, reason: s.reason };
+        const provider = status === analysisStatus ? semanticProviderProvenance() : undefined;
+        return s.available
+            ? { available: true, ...(provider ? { provider } : {}) }
+            : { available: false, reason: s.reason, ...(provider ? { provider } : {}) };
+    }
+    const semantic = typeof req.kind === "string" && Object.hasOwn(semanticHandlers, req.kind)
+        ? semanticHandlers[req.kind] : undefined;
+    if (semantic && !status().available) {
+        return {
+            semantic: { version: SEMANTIC_RESULT_VERSION, status: "unknown", reason: "analysis-unavailable" },
+            execution: { modelRequests: 0, modelCacheHits: 0 },
+        };
+    }
+    if (semantic && typeof req.sourceDigest !== "string") {
+        return {
+            semantic: { version: SEMANTIC_RESULT_VERSION, status: "unknown", reason: "source-changed" },
+            execution: { modelRequests: 0, modelCacheHits: 0 },
+        };
+    }
+    if ((req.kind === "structures") && typeof req.file === "string" && req.sourceDigest !== undefined) {
+        try {
+            const abs = path.resolve(root, req.file);
+            if (!withinDir(abs, root) || !withinDir(fs.realpathSync(abs), fs.realpathSync(root)))
+                return { error: "analysis file outside root" };
+            const digest = createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+            if (digest !== req.sourceDigest)
+                return { error: `source changed during analysis: ${req.file}` };
+        }
+        catch (e) {
+            return { error: String(e) };
+        }
+    }
+    if (req.kind === "project" || req.kind === "structures") {
+        try {
+            if (!status().available)
+                return { error: "consumer/structure analysis unavailable" };
+            if (req.kind === "project")
+                return { project: projectConsumers(root) };
+            if (typeof req.file !== "string" || !req.file)
+                return { error: "structures needs a file" };
+            const abs = path.resolve(root, req.file);
+            if (!withinDir(abs, root) || !withinDir(fs.realpathSync(abs), fs.realpathSync(root)))
+                return { error: "structure file is outside root" };
+            return { structures: functionStructures(req.file, fs.readFileSync(abs, "utf8")) };
+        }
+        catch (e) {
+            return { error: String(e) };
+        }
     }
-    if (req.kind === "bindings" || req.kind === "spans" || req.kind === "calls") {
+    if (req.kind === "bindings" || req.kind === "spans" || req.kind === "calls" || semantic) {
         if (typeof req.file !== "string" || req.file === "") {
             return { error: `ctx.analysis.${req.kind} needs a "file" path` };
         }
@@ -34,30 +109,76 @@ export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, sta
         if (!withinDir(abs, root)) {
             return { error: `ctx.analysis failed: file is outside the search root: ${req.file}` };
         }
+        if (semantic) {
+            const expression = parseExpression(req.expression);
+            const evaluate = semantic(req.query);
+            if (!expression || !evaluate)
+                return {
+                    semantic: { version: SEMANTIC_RESULT_VERSION, status: "unknown", reason: "unsupported-expression" },
+                    execution: { modelRequests: 0, modelCacheHits: 0 },
+                };
+            const model = cachedModel(abs, root, callsCache, callsAnalyzer, req.file, req.sourceDigest);
+            if ("error" in model)
+                return {
+                    semantic: { version: SEMANTIC_RESULT_VERSION, status: "unknown", reason: model.sourceChanged ? "source-changed" : "provider-failure" },
+                    execution: { modelRequests: model.sourceChanged ? 0 : 1, modelCacheHits: 0 },
+                };
+            const execution = { modelRequests: model.cacheHit ? 0 : 1, modelCacheHits: model.cacheHit ? 1 : 0 };
+            const value = (_a = model.file.structure.flow.values.find(item => item.id === expression.id && item.start === expression.start && item.end === expression.end)) !== null && _a !== void 0 ? _a : model.file.structure.flow.values.find(item => item.start === expression.start && item.end === expression.end);
+            const subject = value === undefined ? undefined : rangeOf(value);
+            try {
+                return { semantic: evaluate(req.file, model.source, model.file, expression), execution, ...(subject ? { subject } : {}) };
+            }
+            catch {
+                return { semantic: { version: SEMANTIC_RESULT_VERSION, status: "unknown", reason: "provider-failure" }, execution, ...(subject ? { subject } : {}) };
+            }
+        }
         if (req.kind === "bindings") {
-            return cachedModel(abs, root, modelCache, analyzer, req.file);
+            const model = cachedModel(abs, root, modelCache, analyzer, req.file, typeof req.sourceDigest === "string" ? req.sourceDigest : undefined);
+            return "error" in model ? model : { file: model.file };
+        }
+        if (req.kind === "calls") {
+            const model = cachedModel(abs, root, callsCache, callsAnalyzer, req.file, typeof req.sourceDigest === "string" ? req.sourceDigest : undefined);
+            return "error" in model ? model : { file: model.file };
         }
-        if (req.kind === "calls")
-            return cachedModel(abs, root, callsCache, callsAnalyzer, req.file);
-        return cachedModel(abs, root, spansCache, spansAnalyzer, req.file);
+        const model = cachedModel(abs, root, spansCache, spansAnalyzer, req.file, typeof req.sourceDigest === "string" ? req.sourceDigest : undefined);
+        return "error" in model ? model : { file: model.file };
     }
-    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: available, bindings, spans, calls` };
+    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: ${["available", "bindings", "spans", "calls", "project", "structures", ...Object.keys(semanticHandlers)].join(", ")}` };
+}
+function parseDispositionQuery(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const consumers = value.consumers;
+    return Array.isArray(consumers) && consumers.every(item => typeof item === "string") ? { consumers } : null;
+}
+function parseValuePathQuery(value) { if (!value || typeof value !== "object")
+    return null; const record = value, at = parseExpression(record.at), path = record.path; return at && Array.isArray(path) && path.length > 0 && path.every(item => typeof item === "string") ? { at, path: path } : null; }
+function parseResourceQuery(value) { if (!value || typeof value !== 'object')
+    return null; const record = value, owner = parseExpression(record.owner), release = record.release; return owner && Array.isArray(release) && release.every(item => typeof item === 'string') ? { owner, release } : null; }
+function parseExpression(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const ref = value;
+    return [ref.id, ref.start, ref.end].every(Number.isInteger) ? ref : null;
 }
-// The shared per-file model lifecycle: stat (cache hit on mtime+size),
+// The shared per-file model lifecycle: read (cache hit on content digest),
 // read, compute, cache. Bindings and spans are the same policy over two
 // analyzers and two caches.
-function cachedModel(abs, root, cache, compute, relFile) {
+function cachedModel(abs, root, cache, compute, relFile, expectedDigest) {
     let source;
-    let mtimeMs;
-    let size;
+    let digest;
     try {
-        const stat = fs.statSync(abs);
-        mtimeMs = stat.mtimeMs;
-        size = stat.size;
-        const cached = cache.get(abs);
-        if (cached && cached.mtimeMs === mtimeMs && cached.size === size)
-            return { file: cached.file };
+        if (!withinDir(fs.realpathSync(abs), fs.realpathSync(root)))
+            return { error: "analysis file outside root" };
         source = fs.readFileSync(abs, "utf8");
+        digest = createHash("sha256").update(source).digest("hex");
+        if (expectedDigest !== undefined && digest !== expectedDigest) {
+            return { error: `source changed during analysis: ${relFile}`, sourceChanged: true };
+        }
+        const cached = cache.get(abs);
+        if (cached && cached.digest === digest)
+            return { file: cached.file, source, cacheHit: true };
     }
     catch {
         return { error: `ctx.analysis failed: cannot read ${relFile}` };
@@ -66,6 +187,9 @@ function cachedModel(abs, root, cache, compute, relFile) {
     const r = compute(rel, source);
     if (!r.ok)
         return { error: r.error };
-    cache.set(abs, { mtimeMs, size, file: r.file });
-    return { file: r.file };
+    cache.set(abs, { digest, file: r.file });
+    return { file: r.file, source, cacheHit: false };
+}
+function rangeOf(value) {
+    return { start: value.start, end: value.end, line: value.line, column: value.column, endLine: value.endLine, endColumn: value.endColumn };
 }

package/bin/analysis.d.ts

@@ -7,6 +7,9 @@ export type AnalysisStatusResult = AnalysisStatus | {
     available: false;
     reason: string;
 };
+export declare const SEMANTIC_PROVIDER_ID = "any-doctor/syntax-flow";
+export declare const SEMANTIC_PROVIDER_VERSION = "1";
+export declare function semanticProviderProvenance(): import("./contract.js").SemanticProviderProvenance;
 export declare function analysisStatus(): AnalysisStatusResult;
 export type AnalysisResult = {
     ok: true;
@@ -31,4 +34,14 @@ export type SpansResult = {
 };
 export declare function analyzeSpans(file: string, source: string): SpansResult;
 export declare function analyzeBindings(file: string, source: string): AnalysisResult;
+export type Node = {
+    type: string;
+    range?: [number, number];
+    [k: string]: unknown;
+};
 export declare function analyzeCalls(file: string, source: string): CallsResult;
+/** Host-only AST/scope seam. Doctors receive bounded derived facts, never ASTs. */
+export declare function analyzeSyntax(file: string, source: string): {
+    program: Node;
+    scopes: import("@typescript-eslint/scope-manager").ScopeManager;
+};

package/bin/analysis.js

@@ -1,6 +1,30 @@
+import { callStructure } from "./call-structure.js";
 import { createRequire } from "module";
 let loaded = null;
 const require_ = createRequire(import.meta.url);
+export const SEMANTIC_PROVIDER_ID = "any-doctor/syntax-flow";
+export const SEMANTIC_PROVIDER_VERSION = "1";
+function dependencyVersion(id) {
+    try {
+        return require_(`${id}/package.json`).version;
+    }
+    catch {
+        return "unavailable";
+    }
+}
+export function semanticProviderProvenance() {
+    const state = analysisStatus();
+    return {
+        id: SEMANTIC_PROVIDER_ID,
+        version: SEMANTIC_PROVIDER_VERSION,
+        available: state.available,
+        ...(!state.available ? { reason: state.reason } : {}),
+        dependencies: [
+            { id: "oxc-parser", version: dependencyVersion("oxc-parser") },
+            { id: "@typescript-eslint/scope-manager", version: dependencyVersion("@typescript-eslint/scope-manager") },
+        ],
+    };
+}
 function loadStack() {
     if (loaded !== null)
         return loaded;
@@ -24,7 +48,12 @@ function parseProgram(stack, file, source) {
     if (stack.error !== undefined)
         return { ok: false, error: stack.error };
     try {
-        const parsed = stack.parseSync(file, source, { sourceType: "module" });
+        const lang = /\.tsx$/i.test(file) ? "tsx"
+            : /\.(?:jsx?|mjs|cjs)$/i.test(file) ? "jsx"
+                : /\.d\.ts$/i.test(file) ? "dts"
+                    : /\.(?:ts|mts|cts)$/i.test(file) ? "ts"
+                        : "js";
+        const parsed = stack.parseSync(file, source, { sourceType: "module", lang });
         if (parsed.errors !== undefined && parsed.errors.length > 0) {
             return { ok: false, error: `analysis failed to parse ${file}: ${parsed.errors[0].message}` };
         }
@@ -332,7 +361,7 @@ function lowerBound(sorted, value) {
 // Call relationships and receiver identities are language facts. The doctor
 // decides which imported factory and methods belong to its framework.
 export function analyzeCalls(file, source) {
-    var _a, _b;
+    var _a, _b, _c;
     const stack = loadStack();
     if (stack.error !== undefined)
         return { ok: false, error: stack.error };
@@ -401,14 +430,17 @@ export function analyzeCalls(file, source) {
             var _a;
             let n = unwrap(expr);
             const members = [];
-            while (n.type === "MemberExpression" && !n.computed && isNode(n.object) && isNode(n.property)) {
-                const name = idName(n.property);
+            while ((n.type === "MemberExpression" || n.type === "JSXMemberExpression") && (!n.computed || unwrap(n.property).type === "Literal") && isNode(n.object) && isNode(n.property)) {
+                const name = n.computed ? propertyName(unwrap(n.property)) : idName(n.property);
                 if (!name)
                     break;
                 members.unshift(name);
                 n = unwrap(n.object);
             }
-            if (n.type !== "Identifier")
+            if (n.type === "MetaProperty") {
+                return { root: `${idName(n.meta)}.${idName(n.property)}`, members, binding: null };
+            }
+            if (n.type !== "Identifier" && n.type !== "JSXIdentifier")
                 return { root: null, members, binding: null };
             const identity = identities.get(n);
             return { root: idName(n), members, binding: (_a = identity === null || identity === void 0 ? void 0 : identity.binding) !== null && _a !== void 0 ? _a : null,
@@ -478,7 +510,14 @@ export function analyzeCalls(file, source) {
                     ...range(n), functionStart: functionStart(n), left: operand(n.left), right: operand(n.right),
                 });
         }
-        return { ok: true, file: { file, calls, functions, differences } };
+        const structure = callStructure(nodes, parents, target, range, unwrap, functionStart);
+        const receiverValues = new Map((_c = structure.flow) === null || _c === void 0 ? void 0 : _c.values.filter(value => value.kind === "call" && value.receiver !== undefined).map(value => [value.end, value.receiver]));
+        for (const call of calls) {
+            const receiverValue = receiverValues.get(call.end);
+            if (receiverValue !== undefined)
+                call.receiverValue = receiverValue;
+        }
+        return { ok: true, file: { file, calls, functions, differences, structure } };
     }
     catch (e) {
         return { ok: false, error: `analysis failed for ${file}: ${e instanceof Error ? e.message : String(e)}` };
@@ -486,3 +525,18 @@ export function analyzeCalls(file, source) {
 }
 const FUNCTION_EXPRESSIONS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
 const TRANSPARENT_EXPRESSIONS = new Set(["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSSatisfiesExpression", "ChainExpression", "ParenthesizedExpression"]);
+/** Host-only AST/scope seam. Doctors receive bounded derived facts, never ASTs. */
+export function analyzeSyntax(file, source) {
+    const stack = loadStack();
+    const parsed = parseProgram(stack, file, source);
+    if (!parsed.ok)
+        throw new Error(parsed.error);
+    if (stack.error !== undefined)
+        throw new Error(stack.error);
+    try {
+        return { program: parsed.program, scopes: stack.analyze(parsed.program, { sourceType: "module" }) };
+    }
+    catch (e) {
+        throw new Error(`analysis failed to resolve scopes in ${file}: ${String(e)}`);
+    }
+}

package/bin/authoring.d.ts

@@ -0,0 +1,97 @@
+export declare const AUTHORING_CATALOG_VERSION: 1;
+export declare const AUTHORING_BOUNDARY = "Consumer agents use public facts and recipes; do not patch an installed Any Doctor package or build a private parser/resolver. When public facts are insufficient, narrow the affected check and produce a capability-gap report. Any Doctor maintainers may extend the shared provider only with a framework-neutral change and definite-positive, negative, uncertain, and mixed-neighbor regressions. A capability-gap report is evidence for future product work, not permission to guess or claim a clean result.";
+export declare function authoringCatalog(): {
+    schema: 1;
+    tool: string;
+    command: string;
+    rule: string;
+    sourceAccess: {
+        api: string;
+        purpose: string;
+    }[];
+    capabilities: {
+        api: string;
+        purpose: string;
+        limits?: string[];
+        outcomes?: string[];
+        name: "bindings" | "calls" | "identity" | "option-presence" | "resource-lifetime" | "value-disposition" | "consumers" | "spans" | "value-path" | "structures";
+    }[];
+    recipes: {
+        requires: string[];
+        outcomes: readonly ["report", "clear", "unknown"];
+        api: string;
+        purpose: string;
+        limits: string[];
+        inputSchema: Record<string, unknown>;
+        example: string;
+        name: "forbidden-call" | "required-or-recommended-option" | "resource-without-release" | "unhandled-value";
+    }[];
+    customChecks: {
+        reference: string;
+        boundary: string;
+        procedure: string[];
+        gapReport: {
+            classifications: {
+                "authoring-error": string;
+                "reusable-sdk-gap": string;
+                "project-policy": string;
+                "runtime-dynamic": string;
+            };
+            requiredFields: string[];
+            validation: {
+                api: string;
+                certificationApi: string;
+                consumedByDoctorVerify: boolean;
+                stakes: readonly ["currentFailure", "definitePositive", "negativeControl", "uncertainControl"];
+                stakeFields: {
+                    seed: string;
+                    fixturePath: string;
+                    findings: string;
+                    narrowing: string;
+                    score: string;
+                    grade: string;
+                };
+                constraints: string;
+            };
+            completion: string;
+        };
+    };
+    reporting: {
+        api: string;
+        purpose: string;
+    }[];
+};
+export type AuthoringCatalog = ReturnType<typeof authoringCatalog>;
+/** Validate authoring evidence without executing seeds or claiming their assertions passed. */
+export declare function validateCapabilityGapReport(value: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+export interface CapabilityGapCertificationOptions {
+    /** Doctor program whose accepted claim the report exercises. */
+    doctorPath: string;
+    /** Base for fixturePath stakes. Defaults to the current working directory. */
+    reportDir?: string;
+    /** Test seam for a candidate CLI build. Defaults to this package's CLI. */
+    cliPath?: string;
+    timeoutMs?: number;
+}
+export interface CapabilityGapCaseResult {
+    name: string;
+    ok: boolean;
+    errors: string[];
+}
+export interface CapabilityGapCertificationResult {
+    valid: boolean;
+    validationErrors: string[];
+    passed: number;
+    failed: number;
+    cases: CapabilityGapCaseResult[];
+}
+/**
+ * Execute every declared capability-gap stake through the real CLI and compare
+ * findings, narrowing, scoring and run integrity. This remains separate from
+ * ordinary Doctor verification: a gap report is authoring evidence, not a
+ * Doctor fixture or a new runtime capability.
+ */
+export declare function certifyCapabilityGapReport(value: unknown, options: CapabilityGapCertificationOptions): CapabilityGapCertificationResult;