libvct-spec/spec/015-open-questions.md

015 — Open Questions

• Status: Draft
• Normative language: MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

1. Purpose

This file records the capabilities that v1 deliberately defers. Each item is stated as an open question with the reason for deferral and the work needed to resolve it. The purpose is to separate "not yet designed" from "required and specified", so that readers and implementors do not mistake a gap for a guarantee.

2. Scope and conformance status

Everything in this file is out of scope for v1. These items are not conformance requirements, and they add no behavior an implementation must provide.

1. An implementation MUST NOT be judged non-conforming for omitting any item in this file.
2. An implementation MAY implement any item here. Doing so MUST NOT change the behavior required by the stage files for the features that are in scope.
3. The absence statements already in 000 — Overview, such as the absence of LLVM debug metadata on the LLVM path, describe the v1 scope. They MUST NOT be read as forbidding a future extension.
4. When an item is resolved, it MUST be promoted into a stage file with its own normative requirements; it MUST NOT remain only here.

3. Summary

ID	Open question	v1 status	Would touch
OQ1	LLVM debug info (!llvm.dbg)	Deferred	009 — LLVM Backend
OQ2	Windows and MSVC support	Out of scope	008 — C Backend, 010 — Driver & CLI
OQ3	LLVM bitcode emission	Deferred	009 — LLVM Backend
OQ4	Incremental and cached compilation	Out of scope	010 — Driver & CLI, 013 — Build & Packaging
OQ5	Cross-compilation beyond passthrough	Future work	009 — LLVM Backend, 010 — Driver & CLI

4. OQ1: LLVM debug information

Question. Should the LLVM backend emit !llvm.dbg metadata so that debuggers can map machine state back to frontend source?

v1 behavior. No. The LLVM backend emits no debug metadata. Debug mapping exists only on the C path, through #line directives (see 008 — C Backend).

Why deferred. The C path already provides source mapping for the v1 target, and LLVM debug metadata is a large, version-sensitive surface. Emitting it correctly needs DICompileUnit, DIFile, DISubprogram, DILocation, and scope chain construction, plus a verifier pass that checks the metadata graph. That is a subsystem of its own, and getting it half-right produces misleading debuggers, which is worse than no debug info.

What resolution requires.

• Define how VIR source locations resolve through the LoweringMap and the registered source map (see 011 — Diagnostics).
• Lower those locations to LLVM metadata on the LLVM 18+ schema, including lexical block scopes.
• Add a verification step over the metadata graph, and test it with llvm-dwarfdump and a debugger round-trip in CI.
• Decide whether debug metadata is emitted only under -g and how it interacts with the determinism guarantee.

5. OQ2: Windows and MSVC support

Question. Should libVCT support Windows as a host or target, and MSVC as the C compiler?

v1 behavior. No. v1 is Linux/POSIX-first and supports GCC and Clang only (see 000 — Overview).

Why deferred. The C backend leans on GCC and Clang constructs: __builtin_expect, __builtin_assume_aligned, __builtin_assume, __asm__ fences, #[[]] attributes, and #pragma loop hints. MSVC lacks most of these and spells the rest differently. Beyond the C surface, the driver's compiler discovery, response-file handling, path rules, and ABI (dllexport/dllimport, COFF) all differ. Cosmopolitan mode covers a subset of Windows execution but not MSVC as a backend compiler.

What resolution requires.

• Define an MSVC dialect layer: per-construct mappings for hints, attributes, fences, and pragmas, with a portable fallback where no equivalent exists.
• Extend the driver with cl.exe discovery, argument syntax, and error parsing.
• Specify the Windows ABI surface, including exported symbol decoration and the C runtime.
• Add a Windows CI matrix, which also forces decisions about the xmake build on Windows.

6. OQ3: LLVM bitcode emission

Question. Should the LLVM backend be able to emit bitcode (.bc) directly instead of textual .ll?

v1 behavior. No. The backend emits textual .ll only, and the caller runs llvm-as (see 009 — LLVM Backend). libVCT never links LLVM.

Why deferred. The two obvious routes both carry cost or conflict. Linking LLVM would add a large native dependency and contradict the zero-runtime-dependency rule (see 013 — Build & Packaging). Emitting the LLVM bitstream by hand would require implementing and version-tracking the bitstream container format, which is stable but large and not the intended value of the project. Textual output keeps the backend a pure translator.

What resolution requires.

• Choose a route: an optional LLVM-linked build, a bundled bitstream writer, or a supported external llvm-as invocation driven by the library.
• If the library invokes llvm-as, specify discovery and failure handling the way the C compiler is handled in 010 — Driver & CLI.
• Keep textual emission available, since it is the format the round-trip and FileCheck tests use (see 012 — Testing).

7. OQ4: Incremental and cached compilation

Question. Should libVCT cache compiled objects keyed by a content hash so that repeated compilations skip work?

v1 behavior. No. Content-hash .o caching is out of scope. Every invocation of the pipeline compiles from the input it is given.

Why deferred. Caching is only safe when the cache key captures everything that affects output. The deterministic-output guarantee makes caching feasible, but it also raises the bar: a stale hit would silently violate determinism. The key must cover the input, the full Config, the library version, the trait vocabulary version, the textual IR format version, and the chosen C compiler and its version. The storage, eviction, and concurrency design is a separate feature.

What resolution requires.

• Specify the cache key and prove that no input affecting output is omitted.
• Specify cache storage, invalidation, and locking, including concurrent invocations.
• Expose the feature through the CLI and the API without making it the default.
• Test that a cache hit and a cache miss produce byte-identical output.

8. OQ5: Cross-compilation

Question. Should libVCT support cross-compilation to targets other than the host?

v1 behavior. Partial. -target <triple> passes through to the toolchain, and -mangled mode produces an Actually Portable Executable, but there is no general cross-compilation support. Compiler discovery is host-oriented, and there is no sysroot or header management.

Why deferred. Real cross-compilation needs a target model, not just a flag: target data layout for the LLVM backend, an ABI definition for the C backend, discovery of a target C compiler, and a sysroot with target headers and libraries. The v1 pipeline assumes a host compiler that already knows its target.

What resolution requires.

• Define the supported target matrix and the meaning of a target triple in Config.
• Derive the LLVM target data layout and triple, and validate the module against it.
• Specify cross C compiler discovery, sysroot layout, and header resolution.
• Define the target ABI surface for the C backend and test it on at least one non-host target.

9. Cross-references

• 000 — Overview for the v1 non-goals these questions extend.
• 008 — C Backend for the GCC and Clang constructs behind OQ2 and OQ5.
• 009 — LLVM Backend for the emission surface behind OQ1, OQ3, and OQ5.
• 010 — Driver & CLI for compiler discovery behind OQ2, OQ3, OQ4, and OQ5.
• 011 — Diagnostics for source maps behind OQ1.
• 012 — Testing for the regression and determinism obligations new features must inherit.
• 013 — Build & Packaging for the dependency and versioning rules these features must respect.