mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
774 lines
30 KiB
HTML
774 lines
30 KiB
HTML
<!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 = """
|
||
User types: "if true th"
|
||
State: Syntactically invalid!
|
||
Parser: Error, incomplete conditional
|
||
"""
|
||
|
||
# Structure editing (Hazel approach)
|
||
@dataclass
|
||
class EmptyHole:
|
||
"""⦇ ⦈ - empty hole, no expression yet"""
|
||
def __repr__(self):
|
||
return "⦇⦈"
|
||
|
||
@dataclass
|
||
class NonEmptyHole:
|
||
"""⦇e⦈ - non-empty hole, expression with wrong type"""
|
||
expr: 'Expr'
|
||
def __repr__(self):
|
||
return f"⦇{self.expr}⦈"
|
||
|
||
# Structure edit sequence:
|
||
"""
|
||
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!
|
||
"""
|
||
|
||
print("Structure editing: always syntactically well-formed")</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:
|
||
"""Number literal"""
|
||
value: int
|
||
|
||
@dataclass
|
||
class Var:
|
||
"""Variable"""
|
||
name: str
|
||
|
||
@dataclass
|
||
class Lam:
|
||
"""Lambda: λx.e"""
|
||
param: str
|
||
body: 'UExp'
|
||
|
||
@dataclass
|
||
class Ap:
|
||
"""Application: e₁ e₂"""
|
||
func: 'UExp'
|
||
arg: 'UExp'
|
||
|
||
@dataclass
|
||
class Plus:
|
||
"""Addition: e₁ + e₂"""
|
||
left: 'UExp'
|
||
right: 'UExp'
|
||
|
||
@dataclass
|
||
class EHole:
|
||
"""Empty expression hole: ⦇⦈"""
|
||
pass
|
||
|
||
@dataclass
|
||
class NEHole:
|
||
"""Non-empty hole: ⦇e⦈"""
|
||
expr: 'UExp'
|
||
|
||
UExp = Union[Num, Var, Lam, Ap, Plus, EHole, NEHole]
|
||
|
||
print("Hazelnut: λ-calculus + holes")</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:
|
||
"""Expression with cursor (zipper)"""
|
||
focus: UExp # Current expression under cursor
|
||
context: 'ZContext' # Surrounding context
|
||
|
||
# Zipper contexts (one-hole contexts)
|
||
@dataclass
|
||
class ZTop:
|
||
"""Top level: no surrounding context"""
|
||
def __repr__(self):
|
||
return "□"
|
||
|
||
@dataclass
|
||
class ZLam:
|
||
"""λx.□ - cursor inside lambda body"""
|
||
param: str
|
||
parent_context: 'ZContext'
|
||
|
||
@dataclass
|
||
class ZApL:
|
||
"""□ e - cursor in function position"""
|
||
arg: UExp
|
||
parent_context: 'ZContext'
|
||
|
||
@dataclass
|
||
class ZApR:
|
||
"""e □ - cursor in argument position"""
|
||
func: UExp
|
||
parent_context: 'ZContext'
|
||
|
||
@dataclass
|
||
class ZPlusL:
|
||
"""□ + e - cursor in left operand"""
|
||
right: UExp
|
||
parent_context: 'ZContext'
|
||
|
||
@dataclass
|
||
class ZPlusR:
|
||
"""e + □ - cursor in right operand"""
|
||
left: UExp
|
||
parent_context: 'ZContext'
|
||
|
||
@dataclass
|
||
class ZNEHole:
|
||
"""⦇□⦈ - cursor inside non-empty hole"""
|
||
parent_context: 'ZContext'
|
||
|
||
ZContext = Union[ZTop, ZLam, ZApL, ZApR, ZPlusL, ZPlusR, ZNEHole]
|
||
|
||
# Example: Navigate through expression
|
||
def example_zipper():
|
||
"""
|
||
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)
|
||
"""
|
||
pass
|
||
|
||
print("Zipper: cursor position + surrounding context")</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 = "parent"
|
||
CHILD_1 = "child1"
|
||
CHILD_2 = "child2"
|
||
|
||
# Movement actions
|
||
def move(zexp: ZExp, dir: Direction) -> Optional[ZExp]:
|
||
"""
|
||
Move cursor in direction
|
||
|
||
move parent: Go up to parent
|
||
move child(n): Go down to nth child
|
||
"""
|
||
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) -> ZExp:
|
||
"""
|
||
construct lam x
|
||
|
||
Wrap current expression in λx.□
|
||
If current is ⦇⦈, produces λx.⦇⦈
|
||
"""
|
||
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) -> ZExp:
|
||
"""
|
||
construct ap
|
||
|
||
Current becomes function, add hole for argument
|
||
e → e ⦇⦈
|
||
"""
|
||
func = zexp.focus
|
||
new_ap = Ap(func, EHole())
|
||
return ZExp(new_ap, zexp.context)
|
||
|
||
def construct_plus_left(zexp: ZExp) -> ZExp:
|
||
"""
|
||
construct + L
|
||
|
||
Current becomes right operand, add hole on left
|
||
e → ⦇⦈ + e
|
||
"""
|
||
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) -> ZExp:
|
||
"""
|
||
del
|
||
|
||
Replace current expression with empty hole
|
||
e → ⦇⦈
|
||
"""
|
||
return ZExp(EHole(), zexp.context)
|
||
|
||
print("Edit actions: move, construct, delete")</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 "Num"
|
||
|
||
@dataclass
|
||
class TArrow:
|
||
param: 'Type'
|
||
result: 'Type'
|
||
def __repr__(self):
|
||
return f"({self.param} → {self.result})"
|
||
|
||
@dataclass
|
||
class THole:
|
||
"""Type hole: unknown type"""
|
||
def __repr__(self):
|
||
return "?"
|
||
|
||
Type = Union[TNum, TArrow, THole]
|
||
|
||
# Type consistency (~)
|
||
def consistent(t1: Type, t2: Type) -> bool:
|
||
"""
|
||
Type consistency:
|
||
- ? ~ τ for all τ
|
||
- Num ~ Num
|
||
- (τ₁ → τ₂) ~ (σ₁ → σ₂) if τ₁ ~ σ₁ and τ₂ ~ σ₂
|
||
"""
|
||
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):
|
||
"""
|
||
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)
|
||
"""
|
||
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("Inconsistent expressions automatically wrapped in holes")</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) -> Type:
|
||
"""
|
||
Type-aware action semantics
|
||
|
||
Every action produces typeable result!
|
||
|
||
Example: construct lam x
|
||
Before: ⦇⦈ : τ
|
||
After: λx.⦇⦈ : ? → τ
|
||
(Hole becomes lambda body)
|
||
"""
|
||
pass
|
||
|
||
# Synthesis (⇒) vs Checking (⇐)
|
||
def synth(expr: UExp, gamma: dict) -> Type:
|
||
"""
|
||
Synthesis: Γ ⊢ e ⇒ τ
|
||
|
||
Figure out type from expression
|
||
"""
|
||
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):
|
||
"""
|
||
Checking: Γ ⊢ e ⇐ τ
|
||
|
||
Verify expression has expected type
|
||
"""
|
||
match expr:
|
||
case Lam(x, body):
|
||
if isinstance(expected, TArrow):
|
||
new_gamma = gamma | {x: expected.param}
|
||
check(body, new_gamma, expected.result)
|
||
else:
|
||
# Can't check lambda against non-arrow
|
||
raise TypeError("Expected arrow type for lambda")
|
||
case _:
|
||
# Fallback: synthesize and check consistency
|
||
synth_type = synth(expr, gamma)
|
||
if not consistent(synth_type, expected):
|
||
raise TypeError(f"Inconsistent: {synth_type} !~ {expected}")
|
||
|
||
print("Bidirectional typing ensures actions preserve types")</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:
|
||
"""
|
||
Hazelnut action semantics
|
||
|
||
Judgment: (e, γ, α) → e'
|
||
Given expression e, context γ, action α
|
||
Produces new expression e'
|
||
"""
|
||
|
||
@staticmethod
|
||
def construct_num(zexp: ZExp, n: int) -> ZExp:
|
||
"""
|
||
construct num n
|
||
|
||
Rule:
|
||
e is ⦇⦈
|
||
──────────────
|
||
e → n
|
||
|
||
Replaces empty hole with number
|
||
"""
|
||
if isinstance(zexp.focus, EHole):
|
||
return ZExp(Num(n), zexp.context)
|
||
else:
|
||
raise ValueError("construct num requires empty hole")
|
||
|
||
@staticmethod
|
||
def construct_var(zexp: ZExp, x: str) -> ZExp:
|
||
"""
|
||
construct var x
|
||
|
||
Replaces empty hole with variable
|
||
"""
|
||
if isinstance(zexp.focus, EHole):
|
||
return ZExp(Var(x), zexp.context)
|
||
else:
|
||
raise ValueError("construct var requires empty hole")
|
||
|
||
@staticmethod
|
||
def construct_lam(zexp: ZExp, x: str) -> ZExp:
|
||
"""
|
||
construct lam x
|
||
|
||
Rule:
|
||
──────────────
|
||
e → λx.e
|
||
|
||
Wraps current expression in lambda
|
||
"""
|
||
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) -> ZExp:
|
||
"""
|
||
finish
|
||
|
||
Remove non-empty hole wrapper if types match
|
||
|
||
Rule:
|
||
Γ ⊢ e ⇒ τ
|
||
Γ ⊢ ⦇e⦈ ⇐ τ
|
||
──────────────
|
||
⦇e⦈ → e
|
||
|
||
Only works if types are consistent!
|
||
"""
|
||
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("Action semantics: formal rules from Hazelnut paper")</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:
|
||
"""
|
||
Grove: Commutative edit actions for collaboration
|
||
|
||
Key idea: Actions commute so concurrent edits merge automatically
|
||
"""
|
||
action_id: str
|
||
timestamp: int
|
||
user: str
|
||
action_type: str
|
||
parameters: dict
|
||
|
||
def commute(a1: GroveAction, a2: GroveAction) -> bool:
|
||
"""
|
||
Check if actions commute: a1; a2 ≡ a2; a1
|
||
|
||
Examples:
|
||
- Edits at different locations: commute
|
||
- Edits at same location: conflict (handled specially)
|
||
- Dependent edits: don't commute (serialize)
|
||
"""
|
||
# 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]) -> UExp:
|
||
"""
|
||
Merge concurrent edits using commutative properties
|
||
|
||
Grove ensures most edits commute, reducing conflicts
|
||
"""
|
||
pass
|
||
|
||
print("Grove: Commutative actions for collaborative editing")</code></pre>
|
||
<hr>
|
||
<h2>Patterns</h2>
|
||
<h3>Pattern 1: Progressive Refinement</h3>
|
||
<pre><code class="lang-python">def progressive_refinement_example():
|
||
"""
|
||
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
|
||
"""
|
||
print("Progressive refinement: holes → complete program")</code></pre>
|
||
<h3>Pattern 2: Type-Directed Construction</h3>
|
||
<pre><code class="lang-python">def type_directed_construction(expected_type: Type):
|
||
"""
|
||
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)
|
||
"""
|
||
suggestions = []
|
||
|
||
if isinstance(expected_type, TArrow):
|
||
suggestions.append("construct lam x")
|
||
elif isinstance(expected_type, TNum):
|
||
suggestions.extend(["construct num n", "construct +"])
|
||
|
||
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):
|
||
"""
|
||
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
|
||
"""
|
||
expr_type = synth(expr, {})
|
||
|
||
if not consistent(expr_type, expected):
|
||
# Don't throw error - wrap in hole!
|
||
return NEHole(expr)
|
||
else:
|
||
return expr
|
||
|
||
print("Non-empty holes: graceful error recovery")</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'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> |