The R subset, its boundaries, and the optimizations

The declared type language

Every compiled function begins with declare(type(...)). A declared type is an element mode at a rank:

Element modes are double, integer, and logical (plus the internal xlen index type). Symbolic extents (n, num_states, …) tie argument shapes together and feed shape/domain reasoning; they are how the Viterbi example in vignette("getting-started") relates its matrices and vectors.

# scalar in, vector in, matrix in — all declared
f <- function(x, v, m) {
  declare(type(x = double(NA), v = double(), m = double(3, 3)))
  x * v
}

What “accepted” means: three dispositions

Each R construct has one of three dispositions, and the boundary between them is the spec boundary of the compiler:

• core — compiles to a pure-C kernel with no R C API calls in the hot path.
• boundary — not expressible as a pure kernel, but lowered (under fallback = "auto") to an explicit r_eval boundary node that calls back into R. Rejected under the default fallback = "hard".
• rejected — not accepted in either mode (an honest gap or out of scope).

This table is computed by probing the actual compiler, so it cannot drift from the implementation. It is grounded in R’s own grammar, the yacc grammar src/main/gram.y.

A drop in this coverage, or a core construct silently becoming a boundary, is caught by inst/tinytest/test_tccq_grammar.R.

The semantic model

The subset is small on purpose, and the rules are explicit so they live in the IR and middle-end rather than appearing accidentally in the C emitter:

• a <- expr is a local binding, not mutation.
• x[i] is a checked, 1-based indexed read; x[idx] is a gather.
• x[lo:hi] is a contiguous slice/view (an explicit view1 node), so a reduction over a slice need not copy first.
• a[i] <- v and a[lo:hi] <- v are mutation barriers on local storage.
• Direct mutation of a formal argument (e.g. x[1] <- v on an input) is rejected — inputs are borrowed.

direct_formal_mutation <- function(x, v) {
  declare(type(x = double(NA)), type(v = double()))
  x[1] <- v
  x
}
tccq_compile(direct_formal_mutation, mode = "code")
#> Error:
#> ! indexed assignment currently requires a local vector binding. Write y <- x; y[...] <- value; y instead of mutating formal 'x' directly.

Writing through a local binding is fine: y <- x starts as an alias to the input, and the first indexed write forces materialization into owned storage.

assign_kernel <- function(x, i, v) {
  declare(type(x = double(NA)), type(i = integer()), type(v = double()))
  y <- x
  y[i] <- v
  y
}
unname(tccq_compile(assign_kernel)(c(1, 2, 3), 2L, 10))
#> [1]  1 10  3

The boundary model

Optimization is organized around a three-region split, and the regions are explicit in the IR rather than implied by codegen:

1. Pure-C kernel region — all non-boundary computation: plain C math and loops, no Rf_* calls. This is the only region targeted by optimization.
2. C-API wrapper region — argument/type checks and boundary-call plumbing, emitted with the R C API (TYPEOF, XLENGTH, PROTECT, …).
3. Boundary region — every unsupported or dynamic call, represented as an explicit boundary_call node (currently backed by r_eval). It is a legality barrier: optimization never reorders or fuses across it.

Unsupported calls do not vanish into target special cases. Under the default fallback = "hard" they are an error; under fallback = "auto" they become an inspectable boundary node:

fallback_kernel <- function(x) {
  declare(type(x = double()))
  floor(x)
}
ir <- tccq_compile(fallback_kernel, mode = "ir", fallback = "auto")
ir$ir$result$tag
#> [1] "boundary_call"
ir$boundary_diagnostics[[1]]$original_call
#> [1] "floor(x)"

The optimization pipeline

The frontend lowers declared R into typed IR; the middle-end runs an ordered pass pipeline; the target prints C; a backend compiles it. The default passes (introspected live):

The kernel IR concepts are what make the high-value decisions explicit:

• producer — an element computation over an index domain.
• materialize(producer) — allocate an output and write producer elements.
• fold(op, domain, elem) — reduce an element expression over a domain.

Fusion is therefore an IR rewrite, not an emitter accident. For sum((sin(x) + y) * y), kernelize first represents the reduction as a fold over a materialized producer; fusion rewrites it to a fold over the producer directly:

mod <- tccquickr:::tccq_lower_module(tccquickr:::tccq_frontend(function(x, y) {
  declare(type(x = double(NA), y = double(NA)))
  sum((sin(x) + y) * y)
}))
base_passes <- list(
  tccquickr:::tccq_pass_validate_ir(), tccquickr:::tccq_pass_effects(),
  tccquickr:::tccq_pass_index_normalize(), tccquickr:::tccq_pass_shape_domains(),
  tccquickr:::tccq_pass_kernelize()
)
after_kernelize <- tccquickr:::tccq_run_passes(mod, base_passes)
after_fusion <- tccquickr:::tccq_run_passes(mod, c(base_passes, list(tccquickr:::tccq_pass_fusion())))
after_kernelize
#> <tccq_module>
#>   entry: tccq_entry 
#>   formals:
#>    - x : double[NA] 
#>    - y : double[NA] 
#>   ir: program 
#>   kernel: fold 
#>   result type: double
after_fusion
#> <tccq_module>
#>   entry: tccq_entry 
#>   formals:
#>    - x : double[NA] 
#>    - y : double[NA] 
#>   ir: program 
#>   kernel: fold 
#>   result type: double

The longer view

The current target is C, but the pipeline is built so the high-value decisions (types, ranks, ownership, shape domains, the elementwise domain, boundaries) are made before any target syntax. A lowered IR seam sits between the middle-end and the printers so the same decisions can drive other targets later (Fortran/Rust/devices). The architecture and verification strategy — including the R-as-oracle conformance number and the Lean transformation-soundness proofs — are recorded in the decision records under docs/decisions/ on GitHub.