# 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](000-overview.md), 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](009-llvm-backend.md) |
| OQ2 | Windows and MSVC support | Out of scope | [008 — C Backend](008-c-backend.md), [010 — Driver & CLI](010-driver-cli.md) |
| OQ3 | LLVM bitcode emission | Deferred | [009 — LLVM Backend](009-llvm-backend.md) |
| OQ4 | Incremental and cached compilation | Out of scope | [010 — Driver & CLI](010-driver-cli.md), [013 — Build & Packaging](013-build-packaging.md) |
| OQ5 | Cross-compilation beyond passthrough | Future work | [009 — LLVM Backend](009-llvm-backend.md), [010 — Driver & CLI](010-driver-cli.md) |

## 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](008-c-backend.md)).

**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](011-diagnostics.md)).
- 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](000-overview.md)).

**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](009-llvm-backend.md)). 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](013-build-packaging.md)). 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](010-driver-cli.md).
- Keep textual emission available, since it is the format the round-trip and FileCheck tests use
  (see [012 — Testing](012-testing.md)).

## 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](000-overview.md) for the v1 non-goals these questions extend.
- [008 — C Backend](008-c-backend.md) for the GCC and Clang constructs behind OQ2 and OQ5.
- [009 — LLVM Backend](009-llvm-backend.md) for the emission surface behind OQ1, OQ3, and OQ5.
- [010 — Driver & CLI](010-driver-cli.md) for compiler discovery behind OQ2, OQ3, OQ4, and OQ5.
- [011 — Diagnostics](011-diagnostics.md) for source maps behind OQ1.
- [012 — Testing](012-testing.md) for the regression and determinism obligations new features
  must inherit.
- [013 — Build & Packaging](013-build-packaging.md) for the dependency and versioning rules
  these features must respect.