any-doctor 0.1.2 → 0.2.1

package/CONTEXT.md

@@ -5,11 +5,10 @@ When a term here conflicts with language elsewhere, this file wins.
 
 Current product intent lives in [docs/vision.md](docs/vision.md). For work on
 persistent decisions, history, identity, or team convergence, read the
-[lifecycle design](docs/plans/finding-lifecycle/design.md); the first identity
-delivery (lifecycle M1, slices A1+A2) is planned in
-[analysis improvements](docs/plans/analysis-improvements.md). Their proposed records
-are not implemented interfaces; the glossary below describes current behavior
-unless a term is explicitly marked planned.
+[lifecycle design](docs/plans/finding-lifecycle/design.md). Identity (M1) and
+remembered local decisions (M2) have landed; Git-shared decisions (M3) and
+bounded history (M4) remain planned. The glossary below describes current
+behavior unless a term is explicitly marked planned.
 
 ## Doctor program
 
@@ -88,8 +87,8 @@ tree without rebuilding it. A SiteFinding's readKey
 Text the dashboard copies to the clipboard as one unit of agent work: one
 finding (fixPrompt), every finding of one check (checkFixPrompt), or a
 doctor's whole batch (doctorFixPrompt) — pure functions of Doctor-tree
-types plus the verify command, no terminal required. The lifecycle plan
-(M2) reworks this family toward investigation-first framing and
+types plus the verify command, no terminal required. The local-decision
+delivery (M2) reworked this family toward investigation-first framing and
 authorized decision paths.
 
 ## Gate
@@ -163,6 +162,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 +218,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 +273,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
@@ -326,9 +383,10 @@ Where a doctor program lives: repo-local (`./doctors/`, committed with
 the consuming repo), user-global (`~/.any-doctor/doctors/`, available
 in every repo), or bundled (the first-party pack inside the package,
 read-only — a starting point, not a dependency). Repo-local wins slug
-collisions, then user-global, then bundled. Scanning a target repo
-currently does not persist state in any scope. Planned CLI-owned state is
-separate from doctor discovery and does not grant doctors write capabilities.
+collisions, then user-global, then bundled. Scanning itself remains read-only.
+Recording a review decision creates CLI-owned local state under the target's
+`.any-doctor/` directory; that state is separate from doctor discovery and does
+not grant doctors write capabilities.
 
 ## Skill
 
@@ -348,18 +406,19 @@ positive witness. Unspecified legacy units and unavailable analysis are
 reported as not exercised, not counted as passing. Fixture expectations
 establish tested coverage, not general correctness or independence of labels.
 
-## Lifecycle vocabulary (planned, except where marked landed)
+## Lifecycle vocabulary
 
-These terms describe the accepted direction, not current fields on Finding or
-DoctorCtx. The [design](docs/plans/finding-lifecycle/design.md) owns their data
-and applicability rules.
+These terms describe shipped and planned lifecycle behavior. They are CLI-owned,
+not DoctorCtx capabilities. The [design](docs/plans/finding-lifecycle/design.md)
+owns their data and applicability rules.
 
-- **Finding identity** *(landed in the diff path, D30)*: continuity of one
+- **Finding identity** *(landed in diff and local decisions, D30/D31)*: continuity of one
   occurrence across comparable scans, distinct from its current source
-  coordinates. Host-derived today — check key, file, normalized flagged-line
-  digest, indentation-relative column, and innermost enclosing function span —
-  computed per comparison from one post-scan read, never persisted.
-- **Observation:** evidence that a finding was detected in a particular scan.
+  coordinates. Host-derived today — check key, file, normalized evidence digest,
+  indentation-relative column, and innermost enclosing function span. The CLI
+  computes it from source-bound capture; local decisions persist the resulting key.
+- **Observation** *(planned, M4)*: evidence that a finding was detected in a
+  particular retained scan.
 - **Decision** *(landed locally, D31)*: a reasoned accepted/not-applicable
   disposition with a required reason, stored in the local decisions file,
   reversible, attached to a Finding identity — it changes review state
@@ -371,7 +430,8 @@ and applicability rules.
   matched by cardinality are flagged ambiguous.
 - **No longer detected** *(landed in the diff path)*: absence established by
   compatible, completed coverage.
-- **Claimed fix:** a recorded explanation of remediation, separate from rescan evidence.
+- **Claimed fix** *(planned, M4)*: a recorded explanation of remediation,
+  separate from rescan evidence.
 - **Reassessment** *(landed locally)*: a decision requires review because
   its evidence changed — the finding resurfaces with a warning; the
   decision is never silently carried.

package/README.md

@@ -13,8 +13,9 @@ rescan after changes. Saved doctors run without model inference.
 
 Analysis runs locally without an account, API key, or telemetry. Package/tool
 installation can require downloads; the doctor runtime has no network access.
-Remembered decisions and finding history are [planned](docs/plans/finding-lifecycle/proposal.md),
-not available yet.
+Remembered local decisions persist between runs and resurface when their source
+evidence or doctor meaning changes. Shared project decisions and finding history
+remain [planned](docs/plans/finding-lifecycle/proposal.md).
 
 [![npm version](https://img.shields.io/npm/v/any-doctor.svg)](https://www.npmjs.com/package/any-doctor)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#)
@@ -38,6 +39,13 @@ npx any-doctor@latest run slop   # one doctor, straight to the report
 Non-terminals and CI never see a prompt — output is stable and pipeable
 (`--format json`, or `ANY_DOCTOR_HEADLESS=1`).
 
+During review, press `a` to accept an applicable concern or `x` to mark it not
+applicable; both require a reason. The decision is stored locally under
+`.any-doctor/`, hides the matching occurrence from later active lists, and can
+be inspected or reversed with `any-doctor decisions`. Changed evidence resurfaces
+the finding for reassessment. Local decisions never suppress raw JSON findings or
+change CI gates; keep `.any-doctor/decisions.local.json` untracked.
+
 ## The bundled pack
 
 | Doctor | Discipline | Checks |
@@ -46,12 +54,13 @@ 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
 exact multiset of rule/file/line and optional column, then runs shared innocent
-and sensitivity corpora. Convex checks also declare per-check location coverage;
-legacy undeclared coverage is reported as not exercised. Passing fixtures show
+and sensitivity corpora. Every bundled check declares its reporting unit, and
+occurrence checks carry per-check location coverage. Passing fixtures show
 agreement on those cases, not a general accuracy guarantee. See
 [the reliability protocol](docs/doctor-reliability.md).
 
@@ -123,15 +132,18 @@ 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 |
 | [CONTEXT.md](CONTEXT.md) | Domain glossary — canonical terms |
 | [docs/vision.md](docs/vision.md) | Current goals and product direction |
 | [docs/features.md](docs/features.md) | Available features versus planned work |
-| [docs/plans/analysis-improvements.md](docs/plans/analysis-improvements.md) | Next slice: source evidence, identity, and reliable Git-base comparisons |
-| [docs/plans/finding-lifecycle/proposal.md](docs/plans/finding-lifecycle/proposal.md) | Planned decisions, history, and team workflows |
-| [docs/plans/finding-lifecycle/design.md](docs/plans/finding-lifecycle/design.md) | State ownership, SQLite, Git convergence, and open choices |
+| [docs/plans/analysis-improvements.md](docs/plans/analysis-improvements.md) | Delivered identity work and later analysis opportunities |
+| [docs/plans/finding-lifecycle/proposal.md](docs/plans/finding-lifecycle/proposal.md) | Current local decisions plus planned history and team workflows |
+| [docs/plans/finding-lifecycle/design.md](docs/plans/finding-lifecycle/design.md) | State ownership, Git convergence, future history storage, and open choices |
 | [docs/plans/finding-lifecycle/milestones.md](docs/plans/finding-lifecycle/milestones.md) | Implementation slices and acceptance evidence |
 | [docs/HANDOFF.md](docs/HANDOFF.md) | Current handoff and next bounded task |
 | [docs/decisions.md](docs/decisions.md) | Historical choices and explicit supersessions |
@@ -141,7 +153,9 @@ npx any-doctor@latest run --all --fail-on warning --base origin/main
 
 ## Status
 
-Pre-1.0. The next direction is reliable finding identity, remembered decisions,
-team sharing, and bounded local history. Scanning stays available through npx
-without mandatory initialization. See the [feature map](docs/features.md) for
-current availability. MIT.
+Pre-1.0. Finding identity and remembered local decisions are available. The next
+product phase is real-world adoption and reliability feedback; the next planned
+lifecycle feature is Git-shared project decisions, followed separately by bounded
+local history. Scanning stays available through npx without mandatory
+initialization. See the [feature map](docs/features.md) for current availability.
+MIT.

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)}`);
+    }
+}