feat(jtv): Phase 2 — PataCL coproc integration (12/12 tests)

Grammar: extern_coproc_block + intrinsic_decl + insn_decl + encoding_clause.
AST: ExternCoprocBlock, CoprocItem, CoprocResolution variants.
coproc.rs: resolve_coproc_blocks — PataCL gate eval, block-inclusion pass,
  CoprocNamespace registration. Dead blocks silently dropped; live blocks
  annotated with (live, family).
Interpreter: register_coproc_namespace + ExternCoprocNotYetLowered phase-
  boundary error at call sites (per ADR-0005). Formatter/pretty/typechecker
  exhaustiveness satisfied. All 41 existing tests still pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

Cargo.lock

@@ -60,3 +60,6 @@ tower-lsp = "0.20"
 
 # Internal crates
 jtv-core = { path = "crates/jtv-core" }
+
+# PataCL — compile-time decision layer
+patacl-core = { path = "../patacl/crates/patacl-core" }

Cargo.toml

@@ -22,6 +22,7 @@ thiserror.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 wasm-bindgen.workspace = true
+patacl-core.workspace = true
 
 [dev-dependencies]
 criterion.workspace = true

crates/jtv-core/Cargo.toml

@@ -10,6 +10,7 @@ pub struct Program {
 pub enum TopLevel {
     Module(ModuleDecl),
     Import(ImportStmt),
+    ExternCoproc(ExternCoprocBlock),
     Function(FunctionDecl),
     Control(ControlStmt),
 }
@@ -26,6 +27,56 @@ pub struct ImportStmt {
     pub alias: Option<String>,
 }
 
+// ===== COPROCESSOR DECLARATIONS =====
+
+/// A top-level `extern coproc <gate-name> { ... }` block.
+///
+/// `gate_name` is the name of a gate in a companion `.pata` file.
+/// PataCL evaluates the gate at compile time; if dead, this block is
+/// dropped entirely. If live, `items` are registered in the function
+/// namespace as `ExternCoproc` entries.
+///
+/// `resolved` is `None` until the PataCL resolution pass runs.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ExternCoprocBlock {
+    pub gate_name: String,
+    pub items: Vec<CoprocItem>,
+    pub resolved: Option<CoprocResolution>,
+}
+
+/// Outcome of PataCL gate evaluation for one `extern coproc` block.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CoprocResolution {
+    pub live: bool,
+    pub family: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum CoprocItem {
+    Intrinsic(CoprocIntrinsic),
+    Insn(CoprocInsn),
+}
+
+/// A coprocessor intrinsic — a named builtin with no encoding literal.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CoprocIntrinsic {
+    pub name: String,
+    pub params: Vec<Param>,
+    pub return_type: TypeAnnotation,
+    pub purity: Purity,
+}
+
+/// A custom instruction with an optional opaque encoding string.
+/// The encoding is passed verbatim to the assembler backend.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CoprocInsn {
+    pub name: String,
+    pub params: Vec<Param>,
+    pub return_type: TypeAnnotation,
+    pub purity: Purity,
+    pub encoding: Option<String>,
+}
+
 // ===== CONTROL LANGUAGE (Turing-complete) =====
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]

crates/jtv-core/src/ast.rs

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// (MPL-2.0 is automatic legal fallback until PMPL is formally recognised)
+// Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+
+//! PataCL resolution pass for `extern coproc` blocks (Phase 2).
+//!
+//! Implements Steps 1–3 of the JtV/PataCL integration contract:
+//!   1. Name-resolution: for each `extern coproc <gate-name>` block,
+//!      invoke PataCL with the gate-name and target fact environment.
+//!   2. Block-inclusion: drop blocks whose gate evaluated to dead.
+//!   3. Function-namespace registration: surviving decls are added to a
+//!      `CoprocNamespace` for the interpreter and type-checker to consume.
+//!
+//! Call-site phase-boundary error (Step 4) lives in `interpreter.rs`;
+//! the namespace built here is what triggers it at evaluation time.
+//!
+//! # Usage
+//!
+//! ```rust,ignore
+//! let env = CoprocEnv::from_triple("riscv64gc-unknown-none-elf", &["v"]);
+//! let pata_src = std::fs::read_to_string("coproc/riscv.pata")?;
+//! let (program, ns) = resolve_coproc_blocks(program, &env, Some(&pata_src))?;
+//! ```
+
+use std::collections::HashMap;
+
+use patacl_core::{compile as patacl_compile, env_from_triple, eval::eval_gates, GateResult};
+
+use crate::ast::{
+    CoprocItem, CoprocResolution, ExternCoprocBlock, Program, TopLevel,
+};
+use crate::error::{JtvError, Result};
+
+// ──────────────────────────────────────────────
+// Coproc environment
+// ──────────────────────────────────────────────
+
+/// Build-time environment for PataCL gate evaluation.
+pub struct CoprocEnv {
+    target_triple: String,
+    features: Vec<String>,
+}
+
+impl CoprocEnv {
+    pub fn new(target_triple: impl Into<String>, features: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        CoprocEnv {
+            target_triple: target_triple.into(),
+            features: features.into_iter().map(|f| f.into()).collect(),
+        }
+    }
+
+    /// Convenience constructor — same argument shape as `patacl_core::env_from_triple`.
+    pub fn from_triple(triple: &str, features: &[&str]) -> Self {
+        CoprocEnv::new(triple, features.iter().copied())
+    }
+
+    fn patacl_env(&self) -> patacl_core::FactEnv {
+        let refs: Vec<&str> = self.features.iter().map(|s| s.as_str()).collect();
+        env_from_triple(&self.target_triple, &refs)
+    }
+}
+
+// ──────────────────────────────────────────────
+// Function namespace entry
+// ──────────────────────────────────────────────
+
+/// An extern coproc function registered in the function namespace.
+/// The interpreter uses this to return `ExternCoprocNotYetLowered` at
+/// call sites (per ADR-0005 call-site contract).
+#[derive(Debug, Clone)]
+pub struct CoprocEntry {
+    /// Gate name this decl came from (for the phase-boundary error message).
+    pub gate_name: String,
+    /// ISA family string evaluated from the `.pata` file.
+    pub family: String,
+    pub kind: CoprocKind,
+    pub param_count: usize,
+}
+
+#[derive(Debug, Clone)]
+pub enum CoprocKind {
+    Intrinsic,
+    Insn { encoding: Option<String> },
+}
+
+/// Namespace of surviving extern coproc function entries.
+/// Keyed by function name (unqualified); gate_name is in the value.
+#[derive(Debug, Clone, Default)]
+pub struct CoprocNamespace {
+    pub entries: HashMap<String, CoprocEntry>,
+}
+
+impl CoprocNamespace {
+    pub fn get(&self, name: &str) -> Option<&CoprocEntry> {
+        self.entries.get(name)
+    }
+}
+
+// ──────────────────────────────────────────────
+// Resolution pass
+// ──────────────────────────────────────────────
+
+/// Run the PataCL resolution pass over a parsed JtV program.
+///
+/// For each `extern coproc <gate>` block:
+///   - If `pata_source` is `Some`, evaluate the gate via PataCL.
+///   - If the gate is dead → drop the block.
+///   - If the gate is live (or pata_source is None) → annotate the block
+///     with `CoprocResolution` and add its decls to the namespace.
+///
+/// Returns the modified program (dead blocks removed) and the namespace.
+pub fn resolve_coproc_blocks(
+    program: Program,
+    env: &CoprocEnv,
+    pata_source: Option<&str>,
+) -> Result<(Program, CoprocNamespace)> {
+    // Compile the pata file once, if provided, to get all gate results.
+    let gate_results: HashMap<String, GateResult> = if let Some(src) = pata_source {
+        let gates = patacl_compile(src)
+            .map_err(|e| JtvError::CoprocResolutionFailed {
+                gate: "<pata-file>".into(),
+                detail: e.to_string(),
+            })?;
+        let patacl_env = env.patacl_env();
+        eval_gates(&gates, &patacl_env)
+            .map_err(|e| JtvError::CoprocResolutionFailed {
+                gate: "<pata-file>".into(),
+                detail: e.to_string(),
+            })?
+            .into_iter()
+            .map(|r| (r.name.clone(), r))
+            .collect()
+    } else {
+        HashMap::new()
+    };
+
+    let mut namespace = CoprocNamespace::default();
+    let mut filtered = Vec::with_capacity(program.statements.len());
+
+    for item in program.statements {
+        match item {
+            TopLevel::ExternCoproc(block) => {
+                let (keep, resolved) = resolve_one_block(&block, pata_source, &gate_results)?;
+                if keep {
+                    let family = resolved.as_ref().map(|r| r.family.clone()).unwrap_or_default();
+                    register_block_decls(&block, &family, &mut namespace);
+                    filtered.push(TopLevel::ExternCoproc(ExternCoprocBlock {
+                        resolved,
+                        ..block
+                    }));
+                }
+                // Dead blocks are silently dropped.
+            }
+            other => filtered.push(other),
+        }
+    }
+
+    Ok((Program { statements: filtered }, namespace))
+}
+
+/// Resolve a single block: returns (keep, Option<CoprocResolution>).
+fn resolve_one_block(
+    block: &ExternCoprocBlock,
+    pata_source: Option<&str>,
+    gate_results: &HashMap<String, GateResult>,
+) -> Result<(bool, Option<CoprocResolution>)> {
+    if pata_source.is_none() {
+        // No pata source — treat all blocks as unconditionally live.
+        // Useful during development before .pata files are written.
+        return Ok((true, None));
+    }
+
+    match gate_results.get(&block.gate_name) {
+        Some(result) => {
+            if result.live {
+                Ok((true, Some(CoprocResolution {
+                    live: true,
+                    family: result.family.clone().unwrap_or_default(),
+                })))
+            } else {
+                Ok((false, None))
+            }
+        }
+        None => {
+            // Gate name not found in pata file.
+            // Per ADR-0004 strict semantics, this is a build error.
+            Err(JtvError::CoprocResolutionFailed {
+                gate: block.gate_name.clone(),
+                detail: format!(
+                    "gate `{}` not found in .pata source; \
+                     declare it with `gate {} when <predicate>`",
+                    block.gate_name, block.gate_name
+                ),
+            })
+        }
+    }
+}
+
+/// Register all decls in a live block into the namespace.
+fn register_block_decls(
+    block: &ExternCoprocBlock,
+    family: &str,
+    ns: &mut CoprocNamespace,
+) {
+    for item in &block.items {
+        match item {
+            CoprocItem::Intrinsic(i) => {
+                ns.entries.insert(i.name.clone(), CoprocEntry {
+                    gate_name: block.gate_name.clone(),
+                    family: family.to_string(),
+                    kind: CoprocKind::Intrinsic,
+                    param_count: i.params.len(),
+                });
+            }
+            CoprocItem::Insn(i) => {
+                ns.entries.insert(i.name.clone(), CoprocEntry {
+                    gate_name: block.gate_name.clone(),
+                    family: family.to_string(),
+                    kind: CoprocKind::Insn { encoding: i.encoding.clone() },
+                    param_count: i.params.len(),
+                });
+            }
+        }
+    }
+}

crates/jtv-core/src/coproc.rs

@@ -46,6 +46,21 @@ pub enum JtvError {
 
     #[error("IO error: {0}")]
     IoError(String),
+
+    /// Phase-boundary error: the PataCL gate evaluated to live, the decl was
+    /// registered, but native lowering (Zig FFI / Idris2 ABI / SPARK) is not
+    /// yet implemented. Informational — marks the exact boundary between
+    /// "pata done" and "emission pending" (per JtV ADR-0005).
+    #[error(
+        "extern coproc `{gate}` function `{name}` is live on this target \
+         but native lowering is not yet implemented (Phase 2 boundary — \
+         Zig FFI / Idris2 ABI / SPARK emission pending)"
+    )]
+    ExternCoprocNotYetLowered { gate: String, name: String },
+
+    /// PataCL gate resolution error surfaced during compile-time pass.
+    #[error("PataCL gate resolution failed for `{gate}`: {detail}")]
+    CoprocResolutionFailed { gate: String, detail: String },
 }
 
 impl From<std::io::Error> for JtvError {

crates/jtv-core/src/error.rs

@@ -73,6 +73,14 @@ impl Formatter {
                 self.format_control_stmt(stmt);
                 self.output.push('\n');
             }
+            TopLevel::ExternCoproc(block) => {
+                self.write_indent();
+                self.output.push_str(&format!(
+                    "extern coproc {} {{ /* {} item(s) */ }}\n",
+                    block.gate_name,
+                    block.items.len()
+                ));
+            }
         }
     }