○
Planned This feature is planned but not yet implemented.
Dubious source-block-type-tag syntax — parked pending a design decision.
Code
// ============================================================================
// VERIFIED REGRESSION TEST - DO NOT MODIFY WITHOUT DISCUSSION
// ============================================================================
// Test: Source Scope Capture - THE BREAKTHROUGH
// Feature: Source parameters capture continuation bindings
// Verifies: Continuation variables appear in source.scope.bindings
// ============================================================================
// This test proves that Source parameters capture lexical scope from
// continuation pipelines, enabling true template metaprogramming where
// comptime code can inspect runtime variable bindings!
// ============================================================================
~import std/io
// Event that provides user data
~tor getUserData { }
| data { name: string, age: i32 }
~proc getUserData|zig {
return .{ .data = .{ .name = "Alice", .age = 42 } };
}
const std = @import("std");
// Event that takes Source[HTML] parameter for template rendering
// [comptime|transform] annotation marks this as compile-time transformation
// Transform events receive: source (user args), invocation (for type resolution), program (AST), allocator (memory)
~[comptime|transform]tor renderHTML { source: Source<HTML>, invocation: *const Invocation, program: *const Program, allocator: std.mem.Allocator }
| transformed *const Program
| failed string
~proc renderHTML|zig {
// THE BREAKTHROUGH: Access captured bindings at comptime!
// source.scope.bindings should contain the 'u' binding from the continuation
const ast = @import("ast");
const ast_functional = @import("ast_functional");
// NOTE: allocator is now passed as a parameter!
// First, prove we can see the bindings!
if (source.scope.bindings.len == 0) {
return .{ .failed = "ERROR: No bindings captured!" };
}
// THE BREAKTHROUGH: We have access to the captured binding!
const binding = source.scope.bindings[0];
// Parse the HTML template to find $[...] interpolations and build format string
// THE KEY INSIGHT: Use ast_functional.resolveBindingType()!
// This walks the AST to find the event+branch that produced this binding,
// respecting transform execution order (upstream transforms have already run).
const resolved = ast_functional.resolveBindingType(allocator, binding, invocation, program) catch unreachable;
const type_event_name: []const u8 = resolved.event_name;
const type_branch_name: []const u8 = resolved.branch_name;
const type_fields: []const ast.Field = resolved.fields;
const type_module: []const u8 = resolved.module;
// Parse the HTML template to find $[...] interpolations and build format string
const template = source.text;
var format_buf: [1024]u8 = undefined;
var format_len: usize = 0;
var interpolations: [16][]const u8 = undefined;
var interp_count: usize = 0;
var i: usize = 0;
while (i < template.len) {
if (i + 1 < template.len and template[i] == '$' and template[i + 1] == '[') {
// Found interpolation start
const start = i + 2;
var end = start;
while (end < template.len and template[end] != ']') : (end += 1) {}
if (end < template.len) {
// Extract the expression (e.g., "u.name")
const expr = template[start..end];
interpolations[interp_count] = expr;
interp_count += 1;
// PLACEHOLDER: We'll determine format specifier after we know the field types
// For now, just add a marker we'll replace later
format_buf[format_len] = '{';
format_buf[format_len + 1] = '?';
format_buf[format_len + 2] = '}';
format_len += 3;
i = end + 1;
continue;
}
}
// Regular character - copy to format string
// Normalize whitespace: convert newlines/tabs to spaces, collapse multiple spaces
const c = template[i];
if (c == '\n' or c == '\r' or c == '\t' or c == ' ') {
// Only add space if we have content and last char wasn't already a space
if (format_len > 0 and format_buf[format_len - 1] != ' ') {
format_buf[format_len] = ' ';
format_len += 1;
}
} else {
format_buf[format_len] = c;
format_len += 1;
}
i += 1;
}
// Trim trailing whitespace
while (format_len > 0 and format_buf[format_len - 1] == ' ') {
format_len -= 1;
}
// MOVED: Format string finalization will happen AFTER we know the field types
// Build the interpolation expression arguments
var args_buf: [512]u8 = undefined;
var args_len: usize = 0;
for (0..interp_count) |idx| {
if (idx > 0) {
args_buf[args_len] = ',';
args_buf[args_len + 1] = ' ';
args_len += 2;
}
const interp = interpolations[idx];
std.mem.copyForwards(u8, args_buf[args_len..], interp);
args_len += interp.len;
}
const args_str = allocator.dupe(u8, args_buf[0..args_len]) catch unreachable;
// NOTE: proc_body will be built AFTER we know format_str (after fixing format specifiers)
// Build DottedPath for renderHTML
const path_segments = allocator.alloc([]const u8, 1) catch unreachable;
path_segments[0] = allocator.dupe(u8, "renderHTML") catch unreachable;
const renderHTML_path = ast.DottedPath{
.module_qualifier = allocator.dupe(u8, type_module) catch unreachable,
.segments = path_segments,
};
// Create runtime EventDecl with captured binding as parameter
// We'll reference the derived type name (calculated later from event+branch)
const runtime_fields = allocator.alloc(ast.Field, 1) catch unreachable;
runtime_fields[0] = ast.Field{
.name = allocator.dupe(u8, binding.name) catch unreachable,
.type = allocator.dupe(u8, "__PLACEHOLDER__") catch unreachable, // Will be replaced below
.module_path = null,
.phantom = null,
.is_source = false,
.is_file = false,
.is_embed_file = false,
.expression = null,
.expression_str = null,
.owns_expression = false,
};
var runtime_event = ast.EventDecl{
.path = renderHTML_path,
.input = ast.Shape{ .fields = runtime_fields },
.branches = &[_]ast.Branch{
ast.Branch{
.name = "rendered",
.payload = ast.Shape{ .fields = &[_]ast.Field{
ast.Field{
.name = "html",
.type = "[]const u8",
.module_path = null,
.phantom = null,
.is_source = false,
.is_file = false,
.is_embed_file = false,
.expression = null,
.expression_str = null,
.owns_expression = false,
},
} },
.is_optional = false,
},
},
.is_public = false,
.is_implicit_flow = false,
.annotations = &[_][]const u8{},
.is_pure = false,
.is_transitively_pure = false,
.location = source.location,
.module = allocator.dupe(u8, type_module) catch unreachable,
};
// Now that we have type_fields, fix the format specifiers based on ACTUAL field types
// Replace {?} placeholders with correct format specifiers
var format_idx: usize = 0;
var interp_idx: usize = 0;
while (format_idx < format_len) {
if (format_idx + 2 < format_len and
format_buf[format_idx] == '{' and
format_buf[format_idx + 1] == '?' and
format_buf[format_idx + 2] == '}') {
// Found a placeholder! Get the field name from the interpolation
const expr = interpolations[interp_idx];
// Expression is like "u.name" - extract field name after the dot
const field_name = if (std.mem.indexOf(u8, expr, ".")) |dot_idx|
expr[dot_idx + 1..]
else
expr;
// Look up the field type in type_fields
var format_spec: u8 = 'a'; // Default to {any}
for (type_fields) |field| {
if (std.mem.eql(u8, field.name, field_name)) {
// Determine format spec from field type
if (std.mem.eql(u8, field.type, "[]const u8")) {
format_spec = 's'; // string
} else if (std.mem.eql(u8, field.type, "i32") or
std.mem.eql(u8, field.type, "i64") or
std.mem.eql(u8, field.type, "u32") or
std.mem.eql(u8, field.type, "u64")) {
format_spec = 'd'; // integer
}
break;
}
}
// Replace the ? with the actual format specifier
format_buf[format_idx + 1] = format_spec;
interp_idx += 1;
}
format_idx += 1;
}
const format_str = allocator.dupe(u8, format_buf[0..format_len]) catch unreachable;
// Now we can build proc_body using the finalized format_str!
// Note: std is already imported at module level, so we don't redeclare it here
const proc_body = std.fmt.allocPrint(allocator,
\\const allocator = std.heap.page_allocator;
\\const html = std.fmt.allocPrint(allocator,
\\ "{s}",
\\ .{{{s}}}) catch unreachable;
\\return .{{ .rendered = .{{ .html = html }} }};
, .{format_str, args_str}) catch unreachable;
// Create runtime ProcDecl that implements renderHTML
var runtime_proc = ast.ProcDecl{
.path = renderHTML_path,
// Proc bodies are Source-typed: the synthesized proc carries the
// provenance of the Source block it was rendered from.
.body = ast.Source{ .text = proc_body, .location = source.location, .scope = .{ .bindings = &[_]ast.ScopeBinding{} }, .phantom_type = null },
.annotations = &[_][]const u8{},
.target = allocator.dupe(u8, "zig") catch unreachable,
.is_impl = true,
.is_pure = false,
.is_transitively_pure = false,
.location = source.location,
.module = allocator.dupe(u8, "__PLACEHOLDER__") catch unreachable, // Will be replaced with type_module
};
// Derive type name from event and branch: __GetUserDataData
// Capitalize event name first letter
var event_capitalized: [256]u8 = undefined;
var event_len: usize = 0;
for (type_event_name, 0..) |ch, idx| {
if (idx == 0) {
event_capitalized[event_len] = std.ascii.toUpper(ch);
} else {
event_capitalized[event_len] = ch;
}
event_len += 1;
}
// Capitalize branch name first letter
var branch_capitalized: [256]u8 = undefined;
var branch_len: usize = 0;
for (type_branch_name, 0..) |ch, idx| {
if (idx == 0) {
branch_capitalized[branch_len] = std.ascii.toUpper(ch);
} else {
branch_capitalized[branch_len] = ch;
}
branch_len += 1;
}
// Combine: __EventNameBranchName (compiler-generated type)
const type_alias_name = std.fmt.allocPrint(allocator,
"__{s}{s}",
.{event_capitalized[0..event_len], branch_capitalized[0..branch_len]}
) catch unreachable;
// Now update the runtime field type and module with derived/captured values
allocator.free(runtime_fields[0].type);
runtime_fields[0].type = allocator.dupe(u8, type_alias_name) catch unreachable;
allocator.free(runtime_event.module);
runtime_event.module = allocator.dupe(u8, type_module) catch unreachable;
allocator.free(runtime_proc.module);
runtime_proc.module = allocator.dupe(u8, type_module) catch unreachable;
// Build new Program: transform flows, filter out comptime event+proc, add runtime type+event+proc
// Note: +3 because we're adding a type declaration AND event AND proc (3 new items total)
const new_items = allocator.alloc(ast.Item, program.items.len + 3) catch unreachable;
var idx: usize = 0;
for (program.items) |prog_item| {
// Filter out comptime renderHTML event_decl
if (prog_item == .event_decl) {
const event = prog_item.event_decl;
if (event.path.segments.len == 1 and std.mem.eql(u8, event.path.segments[0], "renderHTML")) {
continue; // Skip comptime event
}
// Transform the captured event to use derived type instead of anonymous struct
if (event.path.segments.len == 1 and std.mem.eql(u8, event.path.segments[0], type_event_name)) {
// Create new branches array with derived type reference
const new_branches = allocator.alloc(ast.Branch, event.branches.len) catch unreachable;
for (event.branches, 0..) |branch, branch_idx| {
if (std.mem.eql(u8, branch.name, type_branch_name)) {
// Replace inline struct with derived type reference
// Use __type_ref convention to signal a named type reference
const type_ref_field = allocator.alloc(ast.Field, 1) catch unreachable;
type_ref_field[0] = ast.Field{
.name = allocator.dupe(u8, "__type_ref") catch unreachable,
.type = allocator.dupe(u8, type_alias_name) catch unreachable,
.module_path = null,
.phantom = null,
.is_source = false,
.is_file = false,
.is_embed_file = false,
.expression = null,
.expression_str = null,
.owns_expression = false,
};
new_branches[branch_idx] = ast.Branch{
.name = branch.name,
.payload = ast.Shape{ .fields = type_ref_field },
.is_optional = branch.is_optional,
.annotations = branch.annotations,
};
} else {
new_branches[branch_idx] = branch;
}
}
// Create transformed getUserData event
const transformed_event = ast.EventDecl{
.path = event.path,
.input = event.input,
.branches = new_branches,
.is_public = event.is_public,
.is_implicit_flow = event.is_implicit_flow,
.annotations = event.annotations,
.is_pure = event.is_pure,
.is_transitively_pure = event.is_transitively_pure,
.location = event.location,
.module = event.module,
};
new_items[idx] = ast.Item{ .event_decl = transformed_event };
idx += 1;
continue;
}
}
// Filter out comptime renderHTML proc_decl
if (prog_item == .proc_decl) {
const proc = prog_item.proc_decl;
if (proc.path.segments.len == 1 and std.mem.eql(u8, proc.path.segments[0], "renderHTML")) {
continue; // Skip comptime proc
}
}
// Transform flows that have renderHTML in their continuation pipelines
if (prog_item == .flow) {
const flow = prog_item.flow;
// Check if any continuation contains renderHTML
var has_renderHTML = false;
for (flow.body.continuations) |cont| {
if (cont.node) |step| {
if (step == .invocation) {
const inv = step.invocation;
if (inv.path.segments.len == 1 and std.mem.eql(u8, inv.path.segments[0], "renderHTML")) {
has_renderHTML = true;
break;
}
}
}
if (has_renderHTML) break;
}
if (has_renderHTML) {
// Transform the flow by transforming its continuations
const new_continuations = allocator.alloc(ast.Continuation, flow.body.continuations.len) catch unreachable;
for (flow.body.continuations, 0..) |cont, cont_idx| {
// Transform the step
var new_step: ?ast.Step = null;
if (cont.node) |step| {
if (step == .invocation) {
const inv = step.invocation;
if (inv.path.segments.len == 1 and std.mem.eql(u8, inv.path.segments[0], "renderHTML")) {
// Transform this invocation - remove Source arg, add binding arg
const transformed_path = ast.DottedPath{
.module_qualifier = inv.path.module_qualifier,
.segments = path_segments,
};
const new_args = allocator.alloc(ast.Arg, 1) catch unreachable;
new_args[0] = ast.Arg{
.name = allocator.dupe(u8, binding.name) catch unreachable,
.value = allocator.dupe(u8, binding.value_ref) catch unreachable,
.source_value = null,
};
// Mark as already transformed to prevent infinite loops
const annotations = allocator.alloc([]const u8, 1) catch unreachable;
annotations[0] = allocator.dupe(u8, "@pass_ran(\"transform\")") catch unreachable;
const new_invocation = ast.Invocation{
.path = transformed_path,
.args = new_args,
.annotations = annotations,
.inserted_by_tap = false,
.from_opaque_tap = false,
};
new_step = ast.Step{ .invocation = new_invocation };
} else {
// Keep step as-is
new_step = step;
}
} else {
// Keep step as-is
new_step = step;
}
}
// Create new continuation with transformed step
new_continuations[cont_idx] = ast.Continuation{
.branch = cont.branch,
.binding = cont.binding,
.binding_type = cont.binding_type,
.is_catchall = cont.is_catchall,
.catchall_metatype = cont.catchall_metatype,
.condition = cont.condition,
.condition_expr = cont.condition_expr,
.node = new_step,
.indent = cont.indent,
.continuations = cont.continuations,
};
}
// Create transformed flow with new continuations
const transformed_flow = ast.Flow{
.body = ast.rootSite(flow.inv().*, new_continuations, flow.location),
.annotations = flow.annotations,
.pre_label = flow.pre_label,
.super_shape = flow.super_shape,
.is_pure = flow.is_pure,
.is_transitively_pure = flow.is_transitively_pure,
.location = flow.location,
.module = flow.module,
};
new_items[idx] = ast.Item{ .flow = transformed_flow };
idx += 1;
continue;
}
}
// Modules can be shared, everything else needs deep copy
if (prog_item == .module_decl) {
new_items[idx] = prog_item;
} else {
new_items[idx] = ast_functional.cloneItem(allocator, &prog_item) catch unreachable;
}
idx += 1;
}
// Create HostTypeDecl with the derived type name and fields
const user_data_type = ast.HostTypeDecl{
.name = type_alias_name,
.shape = ast.Shape{ .fields = type_fields },
};
// Add runtime type alias, event, and proc
new_items[idx] = ast.Item{ .host_type_decl = user_data_type };
new_items[idx + 1] = ast.Item{ .event_decl = runtime_event };
new_items[idx + 2] = ast.Item{ .proc_decl = runtime_proc };
const new_program = allocator.create(ast.Program) catch unreachable;
new_program.* = ast.Program{
.items = new_items,
.module_annotations = program.module_annotations,
.main_module_name = program.main_module_name,
.allocator = allocator,
};
return .{ .transformed = new_program };
}
// THE BREAKTHROUGH TEST: Continuation binding + Source block
// The 'u' from | data u |> should be captured in source.scope.bindings!
~getUserData()
| data u |> renderHTML [HTML]{
<h1>$[u.name]</h1>
<p>Age: $[u.age]</p>
}
| rendered h |> std/io:print.ln(h.html)
Expected output
<h1>Alice</h1> <p>Age: 42</p>
Test Configuration
MUST_RUN NEEDS_RULING
Awaiting ruling:
How is a source block's type tag spelled — `Source<HTML>`, `Source[HTML]`, or not at all? `HTML` here is a compiler ANNOTATION (which source kind), not a phantom type. By the `[state]`→`<state>` migration, `[ ]` is the annotation bracket, so this arguably wants `Source[HTML]`. The parser does the opposite: it REJECTS `Source[HTML]` with KORU033 (invalid phantom-state syntax) and accepts only `Source<HTML>`. Your note from 2026-06-03 goes further than picking a bracket — "we are not sure we even want this syntax". Why it was parked rather than fixed: three layers fail behind it, and each fix is only worth building once the surface is settled. - Parser: continuation-body source-block invocations were dropped; a scoped fix made this parse and flow-check clean and was REVERTED, because no green test exercised it. - Emitter: the next wall — it panics on a source-block invocation in continuation position. - Transform: this test's own ~470-line hand-rolled transform walks `flow.continuations` assuming a shape that a nested continuation body breaks, mis-attaching `| rendered`. Blocks: this test — the only one in the corpus using a source block in continuation position (`| data u |> renderHTML [HTML]{ ... }`); every other source-block test invokes at top level, which works.