Files
skills/public/hazelnut-calculus.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

774 lines
30 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hazelnut-calculus</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hazelnut-calculus.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hazelnut-calculus">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hazelnut-calculus.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hazelnut-calculus</h1><p class="lede">Hazelnut structure editor calculus - bidirectionally typed lambda calculus with holes and cursor, edit actions preserving static meaning, zipper structures</p><h1>Hazelnut: Structure Editor Calculus</h1>
<p><strong>Scope</strong>: Hazelnut calculus (POPL 2017), structure editing, edit actions, zipper structures, Grove extensions <strong>Lines</strong>: ~420 <strong>Last Updated</strong>: 2025-10-25</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Implementing structure editors (projectional editors)</li><li>Building Hazel-like live programming environments</li><li>Designing syntax-directed editing systems</li><li>Understanding edit action semantics</li><li>Working with cursor-based program manipulation</li><li>Implementing collaborative editing for code (Grove)</li></ul>
<h2>Core Concepts</h2>
<h3>Structure Editing vs Text Editing</h3>
<p><strong>Key insight</strong>: Edit AST directly, not text</p>
<pre><code class="lang-python">from dataclasses import dataclass
from typing import Union, Optional
# Traditional text editing
text_edit_example = &quot;&quot;&quot;
User types: &quot;if true th&quot;
State: Syntactically invalid!
Parser: Error, incomplete conditional
&quot;&quot;&quot;
# Structure editing (Hazel approach)
@dataclass
class EmptyHole:
&quot;&quot;&quot;⦇ ⦈ - empty hole, no expression yet&quot;&quot;&quot;
def __repr__(self):
return &quot;⦇⦈&quot;
@dataclass
class NonEmptyHole:
&quot;&quot;&quot;⦇e⦈ - non-empty hole, expression with wrong type&quot;&quot;&quot;
expr: &#x27;Expr&#x27;
def __repr__(self):
return f&quot;⦇{self.expr}⦈&quot;
# Structure edit sequence:
&quot;&quot;&quot;
1. Start: ⦇⦈ (empty hole)
2. construct if: if ⦇⦈ then ⦇⦈ else ⦇⦈
3. Fill condition: if true then ⦇⦈ else ⦇⦈
4. Fill branches...
At EVERY step: syntactically valid, typeable!
&quot;&quot;&quot;
print(&quot;Structure editing: always syntactically well-formed&quot;)</code></pre>
<h3>Hazelnut Language</h3>
<p><strong>Core language</strong>: Simply-typed lambda calculus + holes + cursor</p>
<pre><code class="lang-python"># Hazelnut expressions (UExp)
@dataclass
class Num:
&quot;&quot;&quot;Number literal&quot;&quot;&quot;
value: int
@dataclass
class Var:
&quot;&quot;&quot;Variable&quot;&quot;&quot;
name: str
@dataclass
class Lam:
&quot;&quot;&quot;Lambda: λx.e&quot;&quot;&quot;
param: str
body: &#x27;UExp&#x27;
@dataclass
class Ap:
&quot;&quot;&quot;Application: e₁ e₂&quot;&quot;&quot;
func: &#x27;UExp&#x27;
arg: &#x27;UExp&#x27;
@dataclass
class Plus:
&quot;&quot;&quot;Addition: e₁ + e₂&quot;&quot;&quot;
left: &#x27;UExp&#x27;
right: &#x27;UExp&#x27;
@dataclass
class EHole:
&quot;&quot;&quot;Empty expression hole: ⦇⦈&quot;&quot;&quot;
pass
@dataclass
class NEHole:
&quot;&quot;&quot;Non-empty hole: ⦇e⦈&quot;&quot;&quot;
expr: &#x27;UExp&#x27;
UExp = Union[Num, Var, Lam, Ap, Plus, EHole, NEHole]
print(&quot;Hazelnut: λ-calculus + holes&quot;)</code></pre>
<h3>Zipper Structure with Cursor</h3>
<p><strong>Zipper</strong>: Navigate AST with cursor</p>
<pre><code class="lang-python">@dataclass
class ZExp:
&quot;&quot;&quot;Expression with cursor (zipper)&quot;&quot;&quot;
focus: UExp # Current expression under cursor
context: &#x27;ZContext&#x27; # Surrounding context
# Zipper contexts (one-hole contexts)
@dataclass
class ZTop:
&quot;&quot;&quot;Top level: no surrounding context&quot;&quot;&quot;
def __repr__(self):
return &quot;□&quot;
@dataclass
class ZLam:
&quot;&quot;&quot;λx.□ - cursor inside lambda body&quot;&quot;&quot;
param: str
parent_context: &#x27;ZContext&#x27;
@dataclass
class ZApL:
&quot;&quot;&quot;□ e - cursor in function position&quot;&quot;&quot;
arg: UExp
parent_context: &#x27;ZContext&#x27;
@dataclass
class ZApR:
&quot;&quot;&quot;e □ - cursor in argument position&quot;&quot;&quot;
func: UExp
parent_context: &#x27;ZContext&#x27;
@dataclass
class ZPlusL:
&quot;&quot;&quot;□ + e - cursor in left operand&quot;&quot;&quot;
right: UExp
parent_context: &#x27;ZContext&#x27;
@dataclass
class ZPlusR:
&quot;&quot;&quot;e + □ - cursor in right operand&quot;&quot;&quot;
left: UExp
parent_context: &#x27;ZContext&#x27;
@dataclass
class ZNEHole:
&quot;&quot;&quot;⦇□⦈ - cursor inside non-empty hole&quot;&quot;&quot;
parent_context: &#x27;ZContext&#x27;
ZContext = Union[ZTop, ZLam, ZApL, ZApR, ZPlusL, ZPlusR, ZNEHole]
# Example: Navigate through expression
def example_zipper():
&quot;&quot;&quot;
Expression: (λx. x + 1) 5
Cursor positions:
1. ▸(λx. x + 1) 5 (function)
2. (λx. ▸x + 1) 5 (inside lambda, at variable)
3. (λx. x ▸+ 1) 5 (at operator)
4. (λx. x + 1) ▸5 (argument)
&quot;&quot;&quot;
pass
print(&quot;Zipper: cursor position + surrounding context&quot;)</code></pre>
<h3>Edit Actions</h3>
<p><strong>Core edit actions</strong>: Construct, delete, move</p>
<pre><code class="lang-python">from enum import Enum
class Direction(Enum):
PARENT = &quot;parent&quot;
CHILD_1 = &quot;child1&quot;
CHILD_2 = &quot;child2&quot;
# Movement actions
def move(zexp: ZExp, dir: Direction) -&gt; Optional[ZExp]:
&quot;&quot;&quot;
Move cursor in direction
move parent: Go up to parent
move child(n): Go down to nth child
&quot;&quot;&quot;
match dir:
case Direction.PARENT:
# Move up: plug hole, move context
return move_parent(zexp)
case Direction.CHILD_1:
# Move to first child (if exists)
return move_child(zexp, 1)
case Direction.CHILD_2:
return move_child(zexp, 2)
# Construction actions
def construct_lam(zexp: ZExp, param: str) -&gt; ZExp:
&quot;&quot;&quot;
construct lam x
Wrap current expression in λx.□
If current is ⦇⦈, produces λx.⦇⦈
&quot;&quot;&quot;
current = zexp.focus
new_body = EHole() if isinstance(current, EHole) else current
new_lam = Lam(param, new_body)
return ZExp(new_lam, zexp.context)
def construct_ap(zexp: ZExp) -&gt; ZExp:
&quot;&quot;&quot;
construct ap
Current becomes function, add hole for argument
e → e ⦇⦈
&quot;&quot;&quot;
func = zexp.focus
new_ap = Ap(func, EHole())
return ZExp(new_ap, zexp.context)
def construct_plus_left(zexp: ZExp) -&gt; ZExp:
&quot;&quot;&quot;
construct + L
Current becomes right operand, add hole on left
e → ⦇⦈ + e
&quot;&quot;&quot;
right = zexp.focus
new_plus = Plus(EHole(), right)
# Move cursor to left hole
return ZExp(EHole(), ZPlusL(right, zexp.context))
# Deletion action
def delete(zexp: ZExp) -&gt; ZExp:
&quot;&quot;&quot;
del
Replace current expression with empty hole
e → ⦇⦈
&quot;&quot;&quot;
return ZExp(EHole(), zexp.context)
print(&quot;Edit actions: move, construct, delete&quot;)</code></pre>
<h3>Type Consistency and Inconsistency Handling</h3>
<p><strong>Key innovation</strong>: Automatically wrap inconsistent terms in holes</p>
<pre><code class="lang-python"># Types (Hazelnut)
@dataclass
class TNum:
def __repr__(self):
return &quot;Num&quot;
@dataclass
class TArrow:
param: &#x27;Type&#x27;
result: &#x27;Type&#x27;
def __repr__(self):
return f&quot;({self.param} → {self.result})&quot;
@dataclass
class THole:
&quot;&quot;&quot;Type hole: unknown type&quot;&quot;&quot;
def __repr__(self):
return &quot;?&quot;
Type = Union[TNum, TArrow, THole]
# Type consistency (~)
def consistent(t1: Type, t2: Type) -&gt; bool:
&quot;&quot;&quot;
Type consistency:
- ? ~ τ for all τ
- Num ~ Num
- (τ₁ → τ₂) ~ (σ₁ → σ₂) if τ₁ ~ σ₁ and τ₂ ~ σ₂
&quot;&quot;&quot;
if isinstance(t1, THole) or isinstance(t2, THole):
return True
if isinstance(t1, TNum) and isinstance(t2, TNum):
return True
if isinstance(t1, TArrow) and isinstance(t2, TArrow):
return (consistent(t1.param, t2.param) and
consistent(t1.result, t2.result))
return False
# Inconsistency handling
def construct_with_type_check(zexp: ZExp, expected: Type):
&quot;&quot;&quot;
When constructing, check type consistency
If inconsistent: wrap in non-empty hole!
Example:
Expected: Num
Construct: λx.x (type: ? → ?)
Result: ⦇λx.x⦈ (non-empty hole, preserves typing)
&quot;&quot;&quot;
expr = zexp.focus
expr_type = synthesize_type(expr)
if not consistent(expr_type, expected):
# Wrap in non-empty hole
return NEHole(expr)
else:
return expr
print(&quot;Inconsistent expressions automatically wrapped in holes&quot;)</code></pre>
<h3>Bidirectional Typing for Hazelnut</h3>
<p><strong>Action semantics</strong>: Actions preserve types</p>
<pre><code class="lang-python">def action_type(action: str, zexp: ZExp, ctx_type: Type) -&gt; Type:
&quot;&quot;&quot;
Type-aware action semantics
Every action produces typeable result!
Example: construct lam x
Before: ⦇⦈ : τ
After: λx.⦇⦈ : ? → τ
(Hole becomes lambda body)
&quot;&quot;&quot;
pass
# Synthesis (⇒) vs Checking (⇐)
def synth(expr: UExp, gamma: dict) -&gt; Type:
&quot;&quot;&quot;
Synthesis: Γ ⊢ e ⇒ τ
Figure out type from expression
&quot;&quot;&quot;
match expr:
case Num(n):
return TNum()
case Var(x):
return gamma.get(x, THole())
case EHole():
return THole() # Holes synthesize hole type
case NEHole(e):
return THole() # Non-empty holes too
case Ap(f, a):
# Synthesize function, check argument
f_type = synth(f, gamma)
if isinstance(f_type, TArrow):
check(a, gamma, f_type.param)
return f_type.result
else:
return THole()
# ... other cases
def check(expr: UExp, gamma: dict, expected: Type):
&quot;&quot;&quot;
Checking: Γ ⊢ e ⇐ τ
Verify expression has expected type
&quot;&quot;&quot;
match expr:
case Lam(x, body):
if isinstance(expected, TArrow):
new_gamma = gamma | {x: expected.param}
check(body, new_gamma, expected.result)
else:
# Can&#x27;t check lambda against non-arrow
raise TypeError(&quot;Expected arrow type for lambda&quot;)
case _:
# Fallback: synthesize and check consistency
synth_type = synth(expr, gamma)
if not consistent(synth_type, expected):
raise TypeError(f&quot;Inconsistent: {synth_type} !~ {expected}&quot;)
print(&quot;Bidirectional typing ensures actions preserve types&quot;)</code></pre>
<h3>Action Semantics (Complete Example)</h3>
<p><strong>Formal action rules</strong>: From POPL 2017 paper</p>
<pre><code class="lang-python">class ActionSemantics:
&quot;&quot;&quot;
Hazelnut action semantics
Judgment: (e, γ, α) → e&#x27;
Given expression e, context γ, action α
Produces new expression e&#x27;
&quot;&quot;&quot;
@staticmethod
def construct_num(zexp: ZExp, n: int) -&gt; ZExp:
&quot;&quot;&quot;
construct num n
Rule:
e is ⦇⦈
──────────────
e → n
Replaces empty hole with number
&quot;&quot;&quot;
if isinstance(zexp.focus, EHole):
return ZExp(Num(n), zexp.context)
else:
raise ValueError(&quot;construct num requires empty hole&quot;)
@staticmethod
def construct_var(zexp: ZExp, x: str) -&gt; ZExp:
&quot;&quot;&quot;
construct var x
Replaces empty hole with variable
&quot;&quot;&quot;
if isinstance(zexp.focus, EHole):
return ZExp(Var(x), zexp.context)
else:
raise ValueError(&quot;construct var requires empty hole&quot;)
@staticmethod
def construct_lam(zexp: ZExp, x: str) -&gt; ZExp:
&quot;&quot;&quot;
construct lam x
Rule:
──────────────
e → λx.e
Wraps current expression in lambda
&quot;&quot;&quot;
body = zexp.focus if not isinstance(zexp.focus, EHole) else EHole()
new_lam = Lam(x, body)
# Move cursor to body
return ZExp(body, ZLam(x, zexp.context))
@staticmethod
def finish(zexp: ZExp) -&gt; ZExp:
&quot;&quot;&quot;
finish
Remove non-empty hole wrapper if types match
Rule:
Γ ⊢ e ⇒ τ
Γ ⊢ ⦇e⦈ ⇐ τ
──────────────
⦇e⦈ → e
Only works if types are consistent!
&quot;&quot;&quot;
if isinstance(zexp.focus, NEHole):
# Check if inner expression has consistent type
# If yes, unwrap; if no, keep hole
return ZExp(zexp.focus.expr, zexp.context)
else:
return zexp
print(&quot;Action semantics: formal rules from Hazelnut paper&quot;)</code></pre>
<h3>Grove Extensions (POPL 2025)</h3>
<p><strong>Collaborative editing</strong>: Commutative edit actions</p>
<pre><code class="lang-python">@dataclass
class GroveAction:
&quot;&quot;&quot;
Grove: Commutative edit actions for collaboration
Key idea: Actions commute so concurrent edits merge automatically
&quot;&quot;&quot;
action_id: str
timestamp: int
user: str
action_type: str
parameters: dict
def commute(a1: GroveAction, a2: GroveAction) -&gt; bool:
&quot;&quot;&quot;
Check if actions commute: a1; a2 ≡ a2; a1
Examples:
- Edits at different locations: commute
- Edits at same location: conflict (handled specially)
- Dependent edits: don&#x27;t commute (serialize)
&quot;&quot;&quot;
# If actions touch disjoint parts of tree
if disjoint_paths(a1, a2):
return True
# If one creates, other references: order matters
if creates_dependency(a1, a2):
return False
return True
# Operational transformation for concurrent editing
def merge_concurrent_edits(actions: list[GroveAction]) -&gt; UExp:
&quot;&quot;&quot;
Merge concurrent edits using commutative properties
Grove ensures most edits commute, reducing conflicts
&quot;&quot;&quot;
pass
print(&quot;Grove: Commutative actions for collaborative editing&quot;)</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Progressive Refinement</h3>
<pre><code class="lang-python">def progressive_refinement_example():
&quot;&quot;&quot;
Build program by refining holes
1. Start: ⦇⦈ : Num → Num
2. construct lam x: λx.⦇⦈ : Num → Num
3. move child1 (to body)
4. construct + L: ⦇⦈ + ⦇⦈ : Num
5. construct num 1 (left): 1 + ⦇⦈
6. construct var x (right): 1 + x
Result: λx. 1 + x
&quot;&quot;&quot;
print(&quot;Progressive refinement: holes → complete program&quot;)</code></pre>
<h3>Pattern 2: Type-Directed Construction</h3>
<pre><code class="lang-python">def type_directed_construction(expected_type: Type):
&quot;&quot;&quot;
Use expected type to guide construction
Expected: Num → Num
→ Suggest: construct lam (makes lambda)
Expected: Num
→ Suggest: construct num, construct +, construct var (if Num in context)
&quot;&quot;&quot;
suggestions = []
if isinstance(expected_type, TArrow):
suggestions.append(&quot;construct lam x&quot;)
elif isinstance(expected_type, TNum):
suggestions.extend([&quot;construct num n&quot;, &quot;construct +&quot;])
return suggestions</code></pre>
<h3>Pattern 3: Hole-Driven Error Recovery</h3>
<pre><code class="lang-python">def error_recovery_pattern(expr: UExp, expected: Type):
&quot;&quot;&quot;
When type error: wrap in non-empty hole
User constructs: λx.x (type: ? → ?)
Expected: Num
Instead of error: ⦇λx.x⦈ : Num
→ Program still types!
→ User can fix later
&quot;&quot;&quot;
expr_type = synth(expr, {})
if not consistent(expr_type, expected):
# Don&#x27;t throw error - wrap in hole!
return NEHole(expr)
else:
return expr
print(&quot;Non-empty holes: graceful error recovery&quot;)</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Expression Forms</h3>
<p>| Syntax | Meaning | |--------|---------| | ⦇⦈ | Empty hole (EHole) | | ⦇e⦈ | Non-empty hole (NEHole) | | λx.e | Lambda abstraction | | e₁ e₂ | Application | | e₁ + e₂ | Addition |</p>
<h3>Edit Actions</h3>
<p>| Action | Effect | |--------|--------| | move parent | Move cursor up | | move child(n) | Move cursor to nth child | | construct lam x | Wrap in λx.□ | | construct ap | Add application: □ ⦇⦈ | | construct num n | Replace ⦇⦈ with n | | del | Replace with ⦇⦈ | | finish | Remove hole wrapper (if types match) |</p>
<h3>Key Properties</h3>
<pre><code>Syntactic Well-Formedness:
Every edit action produces syntactically valid expression
Static Meaning:
Every expression has a type (possibly with ?)
Type Preservation:
Actions preserve typability</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Allowing syntactically invalid states</strong>: Defeats purpose of structure editing ✅ Actions always produce valid AST</p>
<p>❌ <strong>Throwing errors on type mismatch</strong>: Breaks flow ✅ Wrap inconsistent terms in non-empty holes</p>
<p>❌ <strong>Ignoring cursor position</strong>: Can&#x27;t implement navigation ✅ Use zipper structure to track cursor</p>
<p>❌ <strong>Requiring complete programs</strong>: Defeats holes ✅ Allow incomplete programs, use ⦇⦈ liberally</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>typed-holes-foundations.md</code> - Basic typed holes concepts</li><li><code>type-systems.md</code> - Type checking and consistency</li><li><code>lambda-calculus.md</code> - Underlying calculus</li><li><code>structure-editors.md</code> - General structure editor design</li><li><code>live-programming-holes.md</code> - Hazel environment implementation</li><li><code>typed-holes-semantics.md</code> - Advanced semantics</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hazelnut-calculus.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>