Before Adding Another Language, Define What “Scan” Means

1. A language badge is easy; a scan contract is hard

Counting files, matching a familiar syntax shape, or displaying a language badge can be useful inventory. It answers a narrow question: a selected repository contains files that look like a supported kind. It does not automatically establish semantic analysis, complete dependency evidence, or compatibility with a reducer. A language name is not a single boolean; a scanner has several capabilities, failure modes, and evidence ceilings.

The repository's file.inventory.v1 rule is therefore valuable without being a semantic promise. Its limitation says that file presence is structural evidence only and does not prove runtime usage. A useful adapter can begin with inventory and syntax facts, then publish reduced or unsupported capability rows where stronger analysis is unavailable. The acceptance contract is what makes that expansion credible: it prevents a badge, a parser, or a green command from silently becoming a broader claim.

2. A scan needs authority

Every scan needs a concrete repository identity and commit SHA, a selected byte set, normalized options, and scanner and extractor versions. Those values belong in the authoritative part of scan-manifest.json. The adapter.scan-truth.conformance.v1 rule requires more than a timestamp or a convenient label: the scan ID must be deterministic from the repository authority, commit, actual analyzed-byte identity, normalized options, and adapter version.

The selected-byte identity is a deterministic SHA-256 digest over framed repository-relative paths, file kinds, lengths, and the actual bytes used by the adapter. A same-size dirty mutation must change the digest and scan ID. Commit SHA alone is insufficient for working-tree bytes: two scans can share a commit while analyzing different local content. Exclusions and includes must govern both inventory and parser or compiler inputs, while persisted evidence keeps the real repository-relative spelling. file.inventory.v1 records structural inventory; the conformance rule adds the authority and mutation contract that makes that inventory trustworthy as scan input.

This is also where a missing toolchain becomes visible. The capability rules describe semantic compilation, syntax fallback, project/config inspection, package/restore awareness, generated or design-time linkage, legacy toolchain signals, and downstream coverage as separate observations. They are not a license to collapse every adapter into one support label.

3. A scan publishes one truthful artifact set

A conforming scan publishes the five required standard artifacts: scan-manifest.json, facts.ndjson, index.sqlite, report.md, and logs/analyzer.log. The manifest carries scan authority and capability truth. NDJSON carries machine-readable facts. SQLite provides a queryable projection. The report explains the bounded result, and the log records sanitized analyzer diagnostics without becoming a source dump.

Publication is transactional. An adapter stages a candidate packet in a sibling temporary directory, verifies the selected snapshot again after extraction, validates the required artifacts, and only then replaces the completed output. A failed replacement attempt must not leave a plausible new success. Malformed or incomplete output must not replace a prior completed packet. A typed failure or explicit partial result is preferable to silently omitting the changed input while retaining the old success story. The conformance harness exercises this boundary with inaccessible inputs and failed replacement attempts.

The static-versus-runtime boundary is useful here: these artifacts describe what the selected static scan could establish, not what an application later did at runtime. A valid packet is a durable evidence boundary, not a deployment certificate.

4. Evidence must survive persistence

When an adapter emits a fact, the useful identity cannot disappear between extraction and storage. Where applicable, persistence must retain the deterministic fact ID, scan ID, repository and commit, fact type, rule ID, evidence tier, direction-bearing source and target identities, repository-relative path, line span, extractor ID and version, coverage, limitations, and supporting identities. These fields make a fact reviewable without publishing raw source snippets.

The round trip matters as much as the first write. facts.ndjson and index.sqlite must not quietly disagree about fact IDs, endpoints, rules, tiers, spans, extractor provenance, coverage, limitations, or support IDs. Unknown or malformed schemas fail closed. If an adapter cannot preserve one field, the result should say that the capability is reduced, unsupported, or not-run; it must not manufacture a value that makes the packet look more complete. The gap guide is the right destination for a missing bridge.

5. Failure must remain visible

A compiler, project-load, parser, dependency, or semantic failure does not always erase every useful observation. An adapter may preserve independently provable structural or syntax evidence, emit rule-backed gaps, and mark coverage reduced. It must not label the resulting packet as a full success merely because one fallback parser returned rows. A missing tool is unsupported or not-run, not passing by assumption.

The capability rules keep these meanings separate. The semantic capability rule summarizes compilation and project-load conditions; its limitations say that a derived status row is not a compiler-symbol observation. The syntax-fallback rule preserves what syntax can show but cannot prove compiler binding, runtime reachability, overload selection, or dependency resolution. The project/config and package/restore rules cover static metadata and restore awareness without proving arbitrary build execution, vulnerability status, transitive closure, or deployment. Generated-design time and legacy-toolchain signals remain bounded static guidance. The downstream-coverage rule keeps no-evidence conclusions coverage-relative.

The checked-in rule IDs make those boundaries addressable: analyzer.capability.semantic.v1, analyzer.capability.syntax-fallback.v1, analyzer.capability.project-config.v1, analyzer.capability.package-restore.v1, analyzer.capability.generated-design-time.v1, analyzer.capability.legacy-toolchain.v1, and analyzer.capability.downstream-coverage.v1. A capability row is not only a count; it is a bounded statement with a rule, tier, limitation, and coverage state.

Unreadable, changed, removed, or excluded inputs also need a visible state. A selected file that cannot be inventoried or re-read should stop publication or produce an explicitly partial result according to the adapter policy. An excluded file is not the same as an unreadable file. An omitted file is not evidence of absence. That distinction is central to a scan contract.

6. Shared truth does not mean semantic parity

.NET, JVM, Python, TypeScript, and Swift have different compilers, project models, package systems, parser boundaries, and semantic ceilings. A neutral conformance profile can define shared truth behavior—authority, byte identity, artifacts, persistence, failure, safety, and determinism— without pretending that every language proves equivalent relationships.

Adapters may use different internal implementations and documented fact-ID formulas. Cross-language digest equality is not required because supported inventories differ. Evidence tiers retain their actual meaning: a semantic row in one ecosystem is not automatically equivalent to a syntax or structural row in another. The conformance rule's limitation is explicit: bounded synthetic validation does not prove semantic parity, build success, runtime reachability, execution, production behavior, or complete dependency coverage.

7. A readiness matrix comes before roadmap expansion

Before broadening a roadmap claim, run the offline synthetic matrix and inspect the row-level result. The closed outcome vocabulary is required, supported, reduced, unsupported, not-applicable, and not-run. A required row is green only when direct executable evidence supports it.

Consider a completely synthetic Language X. The weak claim is: “The scanner found twelve source files and emitted JSON.” The conforming questions are: which exact repository, commit, selected bytes, options, and tool version were analyzed? Did all five artifacts publish transactionally? Did facts preserve rules, tiers, paths, spans, and extractor provenance? Did changed or unreadable input fail loudly? Did identical scans produce deterministic identity? Did reduced semantic coverage remain visible? Can downstream consumers read the evidence, or do they emit an explicit gap? Those questions describe a credible scan without pretending that Language X has semantic parity with another adapter.

8. What passing this contract does not prove

Passing the matrix is an acceptance signal for bounded scan truth, not a universal language-support certificate. It does not prove semantic parity across languages, complete repository understanding, target build success, runtime reachability, execution, production behavior, dependency completeness, framework coverage, business intent, security or vulnerability status, migration readiness, or release approval. It also does not prove readiness for any specific unimplemented language.

Issue #665 remains deferred in the current conformance implementation state. No Go adapter is implemented, promised, or described as supported here. A future Go adapter—or any other future adapter—should pass the relevant contract rows, or carry a documented owner-accepted exception, before TraceMap makes a broad support statement. The roadmap is a planning surface, not evidence of shipped capability. Compare the existing reduced-coverage article, C# identity article, graph-history article, and Swift API-client article for examples of bounded adapter-specific evidence.

This article is a contract explanation, not a scan result. It uses checked-in public contracts and completely synthetic Language X questions. It publishes no private repository, source snippet, raw fact, SQLite content, analyzer log, endpoint, credential, remote, or runtime observation.