Semantic Scala

semantic-scala

Purpose

Use this policy to decide whether ordinary inspection, compiler/test evidence, or a narrow semantic query is warranted in a Scala project. Preserve what the selected tool actually proves, its side effects, and remaining uncertainty.

The compiler, build, and tests remain the final correctness oracle. The semantic commands are microscopes for specific questions, not substitutes for whole-project validation.

Non-goals

• Do not invoke semantic tools merely because Scala files are present.
• Do not assume an unsupported semantic-scala capability exists or modify a project merely to fabricate semantic evidence.
• Do not bypass point-evidence selection by guessing an artifact from path, module, or source-set hints.
• Do not claim canonical type or symbol identity from rendered hover text, display names, hints, or syntax-only summaries.
• Do not use this policy as permission to execute untrusted build code.

Selection ladder

1. Read the relevant source, tests, and project instructions first.
2. If the question is build correctness, use compile, errors, or test.
3. If inspection and build evidence leave a concrete semantic uncertainty, state that uncertainty before querying.
4. Choose the narrowest command that answers it.
5. When the question is specifically which declaration the Presentation Compiler selects at one exact source position, use symbol-at; do not escalate to point-evidence merely because it is more comprehensive.
6. Use point-evidence when source-artifact discovery and unique selection, live point evidence, and conditional reconciliation are themselves decision-relevant, especially when caller-selected artifact routing is the uncertainty.
7. Use CLI-only tasty-point-evidence only when authoritative post-compile typed evidence at one point is decision-relevant, especially for generated compiler-plugin facts that the live harness PC cannot see. It runs a fresh selected Compile; it is not a cheaper hover query.
8. Prefer a configured, functioning MCP tool when that exact capability exists.
9. Do not repeat an expensive query unless inputs changed or the report records a specific reason.
10. Record the actual tool, bounded inputs, result, side effects, and uncertainty.

No semantic query is needed when source and existing tests already answer the question or when only formatting, prose, file movement, or another non-semantic change is involved.

Capability matrix

The public CLI name is semantic-scala. It has more commands than the MCP adapter. The MCP surface is exactly the eight tools named below.

help and version are CLI utility commands. There is no public typeclass-summary, explain-given, explain-extension, infer-type MCP tool, or automatic semantic invocation.

Side effects and approval

Approval is request-local. Never assume that MCP initialization, tool discovery, or approval for a previous request authorizes later build execution.

Use --sbt-java-home only when the target build explicitly requires a known, already-installed JDK and that exact child-sbt selection is in scope. It does not change the harness JVM, discover or install a JDK, or authorize build execution by itself. Omission preserves inherited Java. For sbt-backed type queries, selected-JDK cache reuse is isolated from no-selector reuse; never replace a typed reuse mismatch with refresh without a new explicit decision.

Result interpretation

Separate three layers:

1. Transport/infrastructure: Was the tool found and did the process, transport, JSON parsing, and schema validation succeed?
2. Adapter: For MCP, ok: true means the adapter invocation and payload handling succeeded. Non-zero exits, malformed JSON, schema mismatch, or a transport error are adapter/infrastructure failures.
3. Domain: A parsed payload can report success: false for compile or test. That is useful domain evidence, not an MCP crash.

Apply these constraints:

• Resolved means a type rendering was produced under the recorded context. It is not canonical type identity or whole-project compile proof.
• Unresolved is neutral. It does not distinguish source error, incomplete classpath/context, unsupported hover behavior, or another cause.
• A successful point or type query does not prove the project compiles.
• SemanticDB artifact availability does not prove that every source is covered.
• Source-set, module, and provenance hints are warnings or heuristics unless the factual fields independently establish them; they are not canonical build-target identity.
• ExactMatch is stronger agreement evidence. RangeMatchOnly, SymbolMismatch, and NoMatch remain successful domain outcomes when the adapter succeeds; report them literally and preserve uncertainty.
• Point evidence selects only one unique mapped parsed artifact, then preserves SelectedFresh, SelectedUnverifiable, stale non-selection, ambiguity, unavailable, partial/unparseable, live-unavailable, and unreadable-artifact states. Never turn stale evidence into completed reconciliation, and never treat mtimes or a symbol mismatch as freshness authority.
• effect-summary is syntax-first. Its wrapper categories and names do not prove full effect semantics or compiler-selected intent.
• Warnings and hints must remain labeled as such, separate from factual fields.
• Selected-context/typeclass evidence is not available through the public CLI/MCP surface. Do not infer it from the existing point or symbol commands.

Cost and latency

• Source inspection and existing-test inspection are usually cheapest.
• An explicit SemanticDB file query or one-file syntax summary is narrow and generally cheaper than build-backed work.
• Presentation-compiler queries can require context setup; manual classpaths are bounded but may be incomplete.
• compile, errors, test, and sbt-backed type inference may start sbt, resolve dependencies, compile, or run project code. Treat them as expensive.
• Prefer infer-type-batch only when multiple bounded point queries genuinely share the same sbt context; otherwise use one narrow infer-type.
• Do not rerun unchanged expensive calls for reassurance. Record why a retry is needed, such as a source edit, classpath change, cache-mode decision, or recorded transient transport failure.

Fallback policy

1. Use a configured MCP tool when the needed command is one of the eight and the tool is functioning.
2. Use the staged CLI when no MCP equivalent exists, or after recording an MCP transport/adapter failure.
3. Label the fallback as CLI evidence and record the command used; never report it as MCP success.
4. Do not fall back from explicit cache reuse to fresh or refresh.
5. After failure, do not invent the missing semantic result. Continue with source/build evidence or report the uncertainty.

Data handling and reporting

• Use repository-relative paths in durable reports when practical.
• Avoid exposing tokens, environment values, private absolute paths, dependency caches, raw reasoning, or large tool transcripts.
• Record only the bounded command, context, result, side effects, warnings, and uncertainty needed to support the current task.
• Do not copy source or semantic artifacts across repository boundaries unless the user has authorized it and the destination is appropriate for that data.

Bounded examples

Compiler error: semantic query unnecessary

After reading the failing source and test, run errors --json, apply the smallest diagnostic-driven repair, then run compile --json and relevant tests. Do not query symbols or inferred types unless a concrete uncertainty remains.

Inferred expression type

When an unannotated expression's compiler-rendered type determines the repair, use one CLI-only point query:

semantic-scala infer-type --file src/main/scala/example/Service.scala --line 18 --col 15 --workspace . --sbt-project core --sbt-configuration Compile --json

Report Resolved or Unresolved, recorded context, warnings, and limitations; validate any patch with compile/test.

If this known target requires a different installed JDK, append --sbt-java-home <absolute-directory> to this sbt-backed form. Do not use the flag for narrow-runtime or manual-classpath inference.

Effect wrapper

When a method should preserve F[Option[A]] rather than flatten or substitute the wrapper, query only its file:

semantic-scala effect-summary --file src/main/scala/example/Repo.scala --json

Treat the declared wrapper as syntax-first evidence, then compile and test.

Static/dynamic disagreement

When point evidence and an explicit SemanticDB occurrence disagree, use reconcile-symbol with the exact source position and artifact. Report ExactMatch, RangeMatchOnly, SymbolMismatch, or NoMatch without upgrading the status.

SemanticDB absent or uncertain

Run semanticdb-status --workspace . --json and semanticdb-for-source --workspace . --file <scala> --json first. If matching static evidence is absent and the user has approved build execution, one explicit semantic-scala compile --json may be used to run the project's ordinary root compile. If the user or build metadata already identifies one project ID, semantic-scala compile --sbt-project <id> --json may instead run that project's fixed ordinary Compile scope. The ID must match [A-Za-z][A-Za-z0-9_-]*; it is not arbitrary sbt syntax or discovery. Either build can execute project/plugin code, resolve dependencies, populate caches, and write build outputs. It emits SemanticDB only when the checked-in target build is already configured to do so.

When checked-in target metadata also explicitly requires a known installed JDK, append --sbt-java-home <absolute-directory> to the chosen build command or use MCP sbtJavaHome on exactly semantic_compile, semantic_errors, or semantic_test. Do not infer, download, or globally select a JDK.

When a project ID is already known and shared-source workspace ambiguity is the actual uncertainty, prefer one opt-in target-aware point-evidence --sbt-project <id> request over guessing an artifact path. Its v4 workspace discovery can remain ambiguous while canonical target ownership is unique. Treat its selected-existing-output/external-dependency/JDK context as partial provenance only; target compiler flags and plugins are not replayed. --sbt-scala-version and --sbt-java-home require the project selector. A request cannot inherit a prior sbt ++; trust the receipt's explicit requested and effective axis. Direct reconcile-symbol stays target-independent.

Use --include-existing-internal-outputs (or MCP includeExistingInternalOutputs: true) only when the known selected project's already-built internal Compile products are decision-relevant and v4's selected-output-plus-external context is insufficient. The opt-in requires the project, emits v5, never builds a missing dependency output, and remains PartialExistingCompileOutputs. Preserve its ordered admitted/excluded graph, axis, presence, and contribution receipt. Do not infer arbitrary sbt configuration semantics, complete classpath coverage, generated semantics, or target compiler-option/plugin replay from a resolved v5 point.

Add --require-fresh-internal-outputs (or MCP requireFreshInternalOutputs: true) only when current-source truth of sibling internal outputs matters to the decision. It requires the v5 opt-in and emits v6. Trust only PresentFreshIncluded as contributing; Stale and Unverifiable states are deliberate exclusions. V6 does not run a compile or generators and requires bounded exact configured source-root provenance with no configured generator or managed-source residue; missing or unsafe provenance is Unverifiable. It does not establish selected-target, build, or workspace freshness. Do not select v6 automatically when v4 or v5 answers the narrower question.

After a successful compile, repeat the same status/source lookup or point-evidence query. Preserve these outcomes separately:

• a matching artifact appeared: report its actual unique, ambiguous, or partial state; availability still does not establish coverage or freshness;
• compile succeeded but no matching artifact appeared: do not infer missing source, unsupported Scala, or that SemanticDB is impossible; stop rather than injecting compiler flags/plugins or mutating the build, and ask the project owner to select or enable an appropriate SemanticDB-producing build;
• compile failed: report build failure separately from SemanticDB absence.

If the ordinary root compile is too broad and no project is already known, keep that scope uncertainty explicit rather than guessing a project or substituting a private shell build. A successful selected compile proves only that bounded project invocation, not whole-workspace correctness. When artifacts do exist, use semanticdb-coverage --workspace . --json before making inventory-scoped coverage statements.

Explicit no-tool case

For a Markdown typo, comment rewording, formatting-only edit, or rename already fully constrained by source and tests, use ordinary inspection and the relevant lightweight checks. Do not invoke a semantic tool.