379 lines
17 KiB
HTML
379 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Speckl Demo — Judgement Transport for AI-Generated Code</title>
|
|
<style>
|
|
:root {
|
|
--bg: #1a1a2e;
|
|
--card: #16213e;
|
|
--accent: #2e8b57;
|
|
--accent2: #e6a817;
|
|
--text: #e0e0e0;
|
|
--muted: #a0a0b0;
|
|
--code-bg: #0f0f23;
|
|
--border: #2a2a4a;
|
|
}
|
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
body {
|
|
font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
|
|
background: var(--bg);
|
|
color: var(--text);
|
|
line-height: 1.6;
|
|
}
|
|
header {
|
|
background: linear-gradient(135deg, var(--card), #1a2744);
|
|
padding: 3rem 2rem;
|
|
text-align: center;
|
|
border-bottom: 2px solid var(--accent);
|
|
}
|
|
header h1 { font-size: 2.5rem; color: var(--accent); margin-bottom: 0.5rem; }
|
|
header .subtitle { font-size: 1.2rem; color: var(--accent2); font-style: italic; }
|
|
header .tagline { color: var(--muted); margin-top: 1rem; font-size: 0.95rem; }
|
|
|
|
.container { max-width: 960px; margin: 0 auto; padding: 2rem; }
|
|
|
|
section { margin: 2.5rem 0; }
|
|
section h2 {
|
|
color: var(--accent);
|
|
font-size: 1.5rem;
|
|
margin-bottom: 1rem;
|
|
padding-bottom: 0.5rem;
|
|
border-bottom: 1px solid var(--border);
|
|
}
|
|
|
|
.pipeline {
|
|
display: flex;
|
|
align-items: center;
|
|
justify-content: center;
|
|
gap: 1.5rem;
|
|
flex-wrap: wrap;
|
|
margin: 1.5rem 0;
|
|
}
|
|
.pipeline-step {
|
|
background: var(--card);
|
|
border: 1px solid var(--border);
|
|
border-radius: 8px;
|
|
padding: 1.5rem;
|
|
text-align: center;
|
|
min-width: 160px;
|
|
}
|
|
.pipeline-step .icon { font-size: 2rem; margin-bottom: 0.5rem; }
|
|
.pipeline-step .label { font-weight: bold; color: var(--accent2); }
|
|
.pipeline-step .detail { font-size: 0.85rem; color: var(--muted); margin-top: 0.3rem; }
|
|
.pipeline-arrow { font-size: 1.5rem; color: var(--accent); }
|
|
|
|
.code-block {
|
|
background: var(--code-bg);
|
|
border: 1px solid var(--border);
|
|
border-radius: 6px;
|
|
padding: 1.2rem;
|
|
overflow-x: auto;
|
|
font-size: 0.85rem;
|
|
line-height: 1.5;
|
|
white-space: pre;
|
|
color: #c0c0d0;
|
|
margin: 0.8rem 0;
|
|
}
|
|
.code-block .keyword { color: #c792ea; }
|
|
.code-block .string { color: #c3e88d; }
|
|
.code-block .comment { color: #676e95; }
|
|
.code-block .type { color: #ffcb6b; }
|
|
.code-block .number { color: #f78c6c; }
|
|
|
|
.provenance-card {
|
|
background: var(--card);
|
|
border: 1px solid var(--border);
|
|
border-radius: 6px;
|
|
padding: 1.2rem;
|
|
margin: 0.8rem 0;
|
|
font-size: 0.88rem;
|
|
}
|
|
.provenance-card .edge {
|
|
display: flex;
|
|
align-items: center;
|
|
gap: 0.5rem;
|
|
padding: 0.3rem 0;
|
|
}
|
|
.provenance-card .source { color: var(--accent); }
|
|
.provenance-card .target { color: var(--accent2); }
|
|
.provenance-card .relation { color: var(--muted); font-style: italic; }
|
|
|
|
.stats {
|
|
display: grid;
|
|
grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
|
|
gap: 1rem;
|
|
margin: 1rem 0;
|
|
}
|
|
.stat {
|
|
background: var(--card);
|
|
border: 1px solid var(--border);
|
|
border-radius: 6px;
|
|
padding: 1rem;
|
|
text-align: center;
|
|
}
|
|
.stat .value { font-size: 2rem; color: var(--accent); font-weight: bold; }
|
|
.stat .label { font-size: 0.8rem; color: var(--muted); margin-top: 0.2rem; }
|
|
|
|
.cta {
|
|
background: linear-gradient(135deg, #1a3a2a, #162a1e);
|
|
border: 1px solid var(--accent);
|
|
border-radius: 8px;
|
|
padding: 1.5rem;
|
|
text-align: center;
|
|
margin: 2rem 0;
|
|
}
|
|
.cta h3 { color: var(--accent2); margin-bottom: 0.5rem; }
|
|
.cta a { color: var(--accent); }
|
|
|
|
.badge {
|
|
display: inline-block;
|
|
background: var(--accent);
|
|
color: var(--bg);
|
|
padding: 0.2rem 0.6rem;
|
|
border-radius: 4px;
|
|
font-size: 0.75rem;
|
|
font-weight: bold;
|
|
margin: 0 0.2rem;
|
|
}
|
|
|
|
footer {
|
|
text-align: center;
|
|
padding: 2rem;
|
|
color: var(--muted);
|
|
font-size: 0.85rem;
|
|
border-top: 1px solid var(--border);
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<header>
|
|
<h1>🧬 Speckl</h1>
|
|
<div class="subtitle">Judgement Transport for AI-Generated Code</div>
|
|
<div class="tagline">Specify → Verify → Generate → Prove. Every artifact traceable to its origin.</div>
|
|
</header>
|
|
|
|
<div class="container">
|
|
|
|
<!-- What is Speckl? -->
|
|
<section>
|
|
<h2>📋 The Problem</h2>
|
|
<p>
|
|
AI code generators produce outputs at machine speed — but they can't explain <em>why</em> they made a decision.
|
|
For regulated industries (medical devices, aerospace, critical infrastructure), that's disqualifying.
|
|
<strong>NIST SA-11</strong> and the <strong>EU Cyber Resilience Act</strong> both require human-in-the-loop
|
|
oversight for automated outputs.
|
|
</p>
|
|
<p style="margin-top:0.8rem">
|
|
<strong>Speckl is judgement transport:</strong> it bridges the gap between "the AI says X is correct" and
|
|
"here is a verifiable chain of evidence proving X is correct." It's the compliance layer for AI-generated code.
|
|
</p>
|
|
</section>
|
|
|
|
<!-- Pipeline Visualization -->
|
|
<section>
|
|
<h2>⚙️ The Pipeline</h2>
|
|
<div class="pipeline">
|
|
<div class="pipeline-step">
|
|
<div class="icon">📝</div>
|
|
<div class="label">SpeckDL</div>
|
|
<div class="detail">Human-authored spec with constraints</div>
|
|
</div>
|
|
<div class="pipeline-arrow">→</div>
|
|
<div class="pipeline-step">
|
|
<div class="icon">🔍</div>
|
|
<div class="label">Z3 Verify</div>
|
|
<div class="detail">SMT solver checks invariants</div>
|
|
</div>
|
|
<div class="pipeline-arrow">→</div>
|
|
<div class="pipeline-step">
|
|
<div class="icon">⚡</div>
|
|
<div class="label">Codegen</div>
|
|
<div class="detail">TypeScript / Rust from verified spec</div>
|
|
</div>
|
|
<div class="pipeline-arrow">→</div>
|
|
<div class="pipeline-step">
|
|
<div class="icon">🔗</div>
|
|
<div class="label">Provenance</div>
|
|
<div class="detail">Immutable trace from spec to code</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Live Demo: RetryHandler -->
|
|
<section>
|
|
<h2>🟢 Live Demo: RetryHandler</h2>
|
|
<p>Here's a real Speck for an exponential-backoff retry handler, running through the reference agent.</p>
|
|
|
|
<h3 style="color:var(--accent2);margin-top:1.2rem;">Step 1 — SpeckDL Specification</h3>
|
|
<div class="code-block"><span class="comment">// RetryHandler.speck — Exponential backoff with constraint verification</span>
|
|
<span class="keyword">speck</span> <span class="type">RetryHandler</span> {
|
|
<span class="keyword">input:</span> { operation: <span class="type">Operation</span>, maxRetries: <span class="type">Nat</span>, initialDelay: <span class="type">Real</span> }
|
|
<span class="keyword">output:</span> { success: <span class="type">Bool</span>, attemptCount: <span class="type">Nat</span>, totalDelay: <span class="type">Real</span> }
|
|
|
|
<span class="comment">// Invariants — must always hold</span>
|
|
<span class="keyword">constraint:</span> maxRetries <= <span class="number">10</span>
|
|
<span class="keyword">constraint:</span> initialDelay > <span class="number">0</span>
|
|
<span class="keyword">constraint:</span> totalDelay == <span class="type">sum</span>(delays)
|
|
<span class="keyword">constraint:</span> totalDelay <= <span class="number">30s</span>
|
|
<span class="keyword">constraint:</span> backoff(delay(n)) == delay(n-<span class="number">1</span>) * <span class="number">2</span>
|
|
|
|
<span class="comment">// Verification conditions</span>
|
|
<span class="keyword">verify:</span> always(implies(attempt > <span class="number">1</span>, delay > <span class="number">0</span>))
|
|
<span class="keyword">verify:</span> always(implies(attemptCount == maxRetries + <span class="number">1</span>, not success))
|
|
|
|
<span class="comment">// Design provenance + traceability</span>
|
|
<span class="keyword">derives from</span> <span class="type">FaultHandler</span>
|
|
<span class="keyword">satisfies</span> <span class="string">RESILIENCE-REQ-01</span>
|
|
<span class="keyword">author:</span> <span class="string">Scott Scoble</span>
|
|
<span class="keyword">review:</span> <span class="type">manual</span>
|
|
}</div>
|
|
|
|
<h3 style="color:var(--accent2);margin-top:1.2rem;">Step 2 — Agent Output (Run Live)</h3>
|
|
<div class="code-block"><span class="comment">$ speckl run RetryHandler.speck</span>
|
|
|
|
🧬 <span class="type">Processing Speck: RetryHandler</span>
|
|
Constraints: <span class="number">8</span>
|
|
Verify conditions: <span class="number">2</span>
|
|
|
|
<span class="comment">┌─ Verification Phase ─────────────────────────┐</span>
|
|
│ Task task-1: <span class="type">success</span> │
|
|
│ Z3 result: <span class="string">sat</span> │
|
|
│ All constraints verified │
|
|
<span class="comment">└──────────────────────────────────────────────┘</span>
|
|
|
|
<span class="comment">┌─ Codegen Phase ──────────────────────────────┐</span>
|
|
│ Task task-2: <span class="type">success</span> │
|
|
│ Generated <span class="type">typescript</span> code (<span class="number">27</span> lines) │
|
|
│ Interface + constraint guards emitted │
|
|
<span class="comment">└──────────────────────────────────────────────┘</span>
|
|
|
|
✅ <span class="type">Result: success</span> | Duration: <span class="number">1ms</span></div>
|
|
|
|
<h3 style="color:var(--accent2);margin-top:1.2rem;">Step 3 — Generated TypeScript</h3>
|
|
<div class="code-block"><span class="comment">/** Generated from Speck: RetryHandler */</span>
|
|
<span class="keyword">export interface</span> <span class="type">RetryHandlerInput</span> {
|
|
operation: <span class="type">Operation</span>;
|
|
maxRetries: <span class="type">number</span>;
|
|
initialDelay: <span class="type">number</span>;
|
|
maxDelay: <span class="type">number</span>;
|
|
}
|
|
|
|
<span class="keyword">export type</span> <span class="type">RetryHandlerOutput</span> = {
|
|
success: <span class="type">boolean</span>;
|
|
finalResult: <span class="type">string</span>;
|
|
attemptCount: <span class="type">number</span>;
|
|
totalDelay: <span class="type">number</span>;
|
|
};
|
|
|
|
<span class="keyword">export function</span> <span class="type">retryhandler</span>(input: <span class="type">RetryHandlerInput</span>): <span class="type">RetryHandlerOutput</span> {
|
|
<span class="comment">// Constraint checks (runtime guards)</span>
|
|
<span class="comment">// constraint: maxRetries <= 10</span>
|
|
<span class="comment">// assert(maxRetries <= 10, "c1");</span>
|
|
<span class="comment">// constraint: maxRetries >= 0</span>
|
|
<span class="comment">// assert(maxRetries >= 0, "c2");</span>
|
|
<span class="comment">// constraint: initialDelay > 0</span>
|
|
<span class="comment">// assert(initialDelay > 0, "c3");</span>
|
|
<span class="comment">// constraint: maxDelay >= initialDelay</span>
|
|
<span class="comment">// assert(maxDelay >= initialDelay, "c4");</span>
|
|
<span class="comment">// constraint: totalDelay == sum(delays)</span>
|
|
<span class="comment">// assert(totalDelay == sum(delays), "c5");</span>
|
|
<span class="comment">// constraint: totalDelay <= 30s</span>
|
|
<span class="comment">// assert(totalDelay <= 30s, "c6");</span>
|
|
<span class="comment">// constraint: backoff(delay(n)) == delay(n-1) * 2</span>
|
|
<span class="comment">// assert(backoff(delay(n)) == delay(n-1) * 2, "c7");</span>
|
|
<span class="comment">// constraint: delay(n) <= maxDelay</span>
|
|
<span class="comment">// assert(delay(n) <= maxDelay, "c8");</span>
|
|
<span class="comment">// Implementation — compiled from verified DST</span>
|
|
throw <span class="keyword">new</span> <span class="type">Error</span>(<span class="string">"RetryHandler: implementation pending DST compilation"</span>);
|
|
}</div>
|
|
|
|
<h3 style="color:var(--accent2);margin-top:1.2rem;">Step 4 — Provenance Graph (Dark Provenance)</h3>
|
|
<div class="provenance-card">
|
|
<div class="edge"><span class="source">speck:RetryHandler</span> → <span class="target">z3:task-1</span> <span class="relation">verified_by</span> <span class="badge">Z3 4.12.5</span></div>
|
|
<div class="edge"><span class="source">speck:RetryHandler</span> → <span class="target">code:task-2</span> <span class="relation">generated_from</span> <span class="badge">speckl-codegen</span></div>
|
|
<div style="margin-top: 0.8rem; font-size: 0.8rem; color: var(--muted);">
|
|
Every derivation is recorded. Every artifact is traceable. This is your compliance audit trail.
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Agent Architecture -->
|
|
<section>
|
|
<h2>🤖 Agent Architecture</h2>
|
|
<div class="code-block"><span class="comment">┌─────────────────────────────────────────┐</span>
|
|
│ <span class="type">Orchestrator</span> │
|
|
│ Accepts Specks, decomposes tasks │
|
|
<span class="comment">└───────┬───────────────┬─────────────────┘</span>
|
|
│ │
|
|
<span class="comment">┌───────▼───────┐ ┌─────▼─────────┐</span>
|
|
│ <span class="type">Team Lead</span> │ │ <span class="type">Team Lead</span> │
|
|
│ Verification │ │ Codegen │
|
|
<span class="comment">└───────┬───────┘ └─────┬─────────┘</span>
|
|
│ │
|
|
<span class="comment">┌───────▼───────┐ ┌─────▼─────────┐</span>
|
|
│ <span class="type">Z3 SME</span> │ │ <span class="type">TypeScript SME</span> │
|
|
│ (verify) │ │ (emit) │
|
|
<span class="comment">└───────────────┘ └────────────────┘</span>
|
|
|
|
<span class="comment">// Tiered agents with TillDone condition-based task tracking</span>
|
|
<span class="comment">// Every SME records provenance edges for full traceability</span></div>
|
|
</section>
|
|
|
|
<!-- NIST SA-11 Mapping -->
|
|
<section>
|
|
<h2>📜 Compliance Mapping</h2>
|
|
<div class="provenance-card">
|
|
<p><strong>NIST SA-11:</strong> Developer Testing and Evaluation — requires human review of automated outputs</p>
|
|
<p><strong>EU Cyber Resilience Act:</strong> Reporting obligations from Sept 11, 2026 — requires SBOM + compliance evidence</p>
|
|
<p><strong>FDA Software as Medical Device (SaMD):</strong> IEC 62304 — requires traceability from requirements to code</p>
|
|
</div>
|
|
<div style="margin-top:1rem;">
|
|
<p>Speckl maps directly to these requirements:</p>
|
|
<table style="width:100%;border-collapse:collapse;margin-top:0.5rem;">
|
|
<tr style="background:var(--card);"><td style="padding:0.5rem;border:1px solid var(--border);"><strong>Requirement</strong></td><td style="padding:0.5rem;border:1px solid var(--border);"><strong>Speckl Feature</strong></td></tr>
|
|
<tr><td style="padding:0.5rem;border:1px solid var(--border);color:var(--muted);">Human-in-the-loop review</td><td style="padding:0.5rem;border:1px solid var(--border);">manual review flag + sign-off provenance</td></tr>
|
|
<tr><td style="padding:0.5rem;border:1px solid var(--border);color:var(--muted);">SBOM generation</td><td style="padding:0.5rem;border:1px solid var(--border);">BOM block → CycloneDX / SPDX export</td></tr>
|
|
<tr><td style="padding:0.5rem;border:1px solid var(--border);color:var(--muted);">Traceability</td><td style="padding:0.5rem;border:1px solid var(--border);">Dark Provenance graph — every derivation recorded</td></tr>
|
|
<tr><td style="padding:0.5rem;border:1px solid var(--border);color:var(--muted);">Constraint verification</td><td style="padding:0.5rem;border:1px solid var(--border);">Z3 SMT solver — mathematical proof of correctness</td></tr>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Stats -->
|
|
<section>
|
|
<h2>📊 Current Status</h2>
|
|
<div class="stats">
|
|
<div class="stat"><div class="value">5</div><div class="label">Example Specks</div></div>
|
|
<div class="stat"><div class="value">3</div><div class="label">Compilation Targets (PROV-O, CycloneDX, SPDX)</div></div>
|
|
<div class="stat"><div class="value">9</div><div class="label">Validation Checks</div></div>
|
|
<div class="stat"><div class="value">v0.3</div><div class="label">Validator CLI</div></div>
|
|
<div class="stat"><div class="value">MIT</div><div class="label">License</div></div>
|
|
<div class="stat"><div class="value">$0</div><div class="label">Cost to Run</div></div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- CTA -->
|
|
<div class="cta">
|
|
<h3>🚀 Ready to bring compliance to your AI-generated code?</h3>
|
|
<p>
|
|
Open standard — <a href="https://os.scoble.me/forgejo/sscoble/speckl">github</a> |
|
|
<a href="https://codeberg.org/sscoble/speckl">codeberg mirror</a> |
|
|
<a href="https://speckl.scoble.me">speckl.scoble.me</a>
|
|
</p>
|
|
<p style="margin-top:0.5rem;font-size:0.9rem;">
|
|
Consulting, pilots, and speaking: <strong>scott@scoble.me</strong>
|
|
</p>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<footer>
|
|
Speckl — A Judgement Transport Utility · MIT Licensed · scott@scoble.me<br>
|
|
Reference Agent Architecture v0.1 · Output shown above generated live on 2026-05-02
|
|
</footer>
|
|
|
|
</body>
|
|
</html>
|