diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 618e296..88257e6 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -49,6 +49,8 @@ jobs: test -f _site/sitemap.xml test -f _site/assets/marginal-readme-hero.png test -f _site/demo/RESULTS.md + test -f _site/demo/demo.css + test -f _site/demo/demo.js - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/demos/killer-demo/comparison.svg b/demos/killer-demo/comparison.svg index 1b60c69..556b53a 100644 --- a/demos/killer-demo/comparison.svg +++ b/demos/killer-demo/comparison.svg @@ -1,14 +1,13 @@ - - + + - -MARGINAL DEMO 001 -Same verified fix. Less declared demo compute. -Deterministic action-cost illustration — not provider telemetry. -Without MARGINAL · Baseline - +MARGINAL DEMO 002 +Same task. Same PASS. Less extra work. +Deterministic action-cost replay — not provider telemetry. +Baseline · execute every candidate + 72,800 -With MARGINAL +MARGINAL · decide before spend 4,300 94.09% fewer declared tokens diff --git a/demos/killer-demo/demo.css b/demos/killer-demo/demo.css new file mode 100644 index 0000000..9661abf --- /dev/null +++ b/demos/killer-demo/demo.css @@ -0,0 +1,457 @@ +:root { + --bg: #06080b; + --panel: #0c1117; + --panel-2: #101720; + --line: #26313d; + --text: #f7fbff; + --muted: #8f9aa8; + --lime: #91ff63; + --cyan: #58e6ff; + --red: #ff675f; + --amber: #f5c451; + --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; + --sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif; +} +* { box-sizing: border-box; } +html { background: var(--bg); scroll-behavior: smooth; } +body { + margin: 0; + min-width: 320px; + color: var(--text); + background: + radial-gradient(circle at 80% 4%, rgba(145,255,99,.12), transparent 25rem), + radial-gradient(circle at 15% 65%, rgba(88,230,255,.06), transparent 32rem), + var(--bg); + font-family: var(--sans); +} +a { color: inherit; text-decoration: none; } +button, select { font: inherit; } +button { cursor: pointer; } +.browser-shell { + width: min(calc(100% - 24px), 1540px); + margin: 12px auto; + border: 1px solid #202a34; + border-radius: 24px; + overflow: hidden; + background: rgba(6,8,11,.96); + box-shadow: 0 44px 140px rgba(0,0,0,.48); +} +.chrome { + display: flex; + align-items: center; + gap: 8px; + height: 42px; + padding: 0 16px; + border-bottom: 1px solid #1d252e; + background: #10151b; +} +.chrome i { + width: 9px; + height: 9px; + border-radius: 50%; + background: #3a4652; +} +.chrome i:first-child { background: #ff6058; } +.chrome i:nth-child(2) { background: #ffbd44; } +.chrome i:nth-child(3) { background: #00ca4e; } +.address { + margin: auto; + color: #73808d; + font: 10px var(--mono); +} +.shell { + width: min(calc(100% - 40px), 1400px); + margin: auto; +} +.topbar { + display: flex; + align-items: center; + justify-content: space-between; + min-height: 64px; + border-bottom: 1px solid var(--line); +} +.brand { + display: flex; + align-items: center; + gap: 10px; + font-size: 13px; + font-weight: 900; + letter-spacing: .12em; +} +.brand-mark { + display: grid; + width: 34px; + height: 34px; + place-items: center; + border: 1px solid rgba(145,255,99,.34); + border-radius: 9px; + color: var(--lime); + background: rgba(145,255,99,.05); +} +.navlinks { display: flex; gap: 18px; color: var(--muted); font-size: 12px; } +.hero { + display: grid; + grid-template-columns: minmax(0,1fr) auto; + gap: 30px; + align-items: end; + padding: 48px 0 28px; +} +.eyebrow { + color: var(--lime); + font: 800 11px var(--mono); + letter-spacing: .13em; +} +h1 { + max-width: 980px; + margin: 10px 0 12px; + font-size: clamp(40px, 5.8vw, 82px); + line-height: .94; + letter-spacing: -.055em; +} +.hero p { max-width: 840px; margin: 0; color: #bdc8d3; font-size: 17px; } +.controls { + display: flex; + flex-wrap: wrap; + justify-content: flex-end; + gap: 8px; +} +.control { + min-height: 42px; + padding: 0 14px; + border: 1px solid var(--line); + border-radius: 9px; + color: var(--text); + background: #0e141b; + font-size: 12px; + font-weight: 800; +} +.control.primary { + border-color: var(--lime); + color: #081005; + background: var(--lime); +} +.control:disabled { cursor: not-allowed; opacity: .42; } +.speed { + min-height: 42px; + padding: 0 10px; + border: 1px solid var(--line); + border-radius: 9px; + color: var(--text); + background: #0e141b; +} +.race-wrap { + position: relative; + margin-bottom: 38px; + border: 1px solid var(--line); + border-radius: 22px; + overflow: hidden; + background: #080c11; +} +.task-strip { + display: grid; + grid-template-columns: 1fr auto 1fr; + gap: 18px; + align-items: center; + min-height: 58px; + padding: 10px 16px; + border-bottom: 1px solid var(--line); + background: #0b1016; +} +.task-strip strong { font-size: 12px; } +.task-strip small { color: var(--muted); font: 10px var(--mono); } +.task-strip .center { color: var(--lime); text-align: center; } +.stage-rail { + position: relative; + display: grid; + grid-template-columns: repeat(3,1fr); + border-bottom: 1px solid var(--line); +} +.stage-node { + position: relative; + padding: 10px 14px; + color: #65717e; + font: 800 10px var(--mono); + letter-spacing: .09em; + text-align: center; +} +.stage-node + .stage-node { border-left: 1px solid var(--line); } +.stage-node.active { color: var(--text); background: rgba(88,230,255,.05); } +.stage-node.done { color: var(--lime); } +.progress-line { + position: absolute; + right: 0; + bottom: 0; + left: 0; + height: 2px; + background: #1f2933; +} +.progress-line span { + display: block; + width: 0; + height: 100%; + background: linear-gradient(90deg, var(--lime), var(--cyan)); + transition: width .35s ease; +} +.race-grid { + display: grid; + grid-template-columns: minmax(0,1fr) 72px minmax(0,1fr); + min-height: 610px; +} +.lane { + min-width: 0; + padding: 18px; + background: var(--panel); +} +.lane.baseline { box-shadow: inset 0 3px 0 rgba(255,103,95,.62); } +.lane.marginal { + background: + radial-gradient(circle at 80% 0, rgba(145,255,99,.06), transparent 18rem), + var(--panel); + box-shadow: inset 0 3px 0 rgba(145,255,99,.72); +} +.lane.flash { animation: lane-flash .46s ease; } +@keyframes lane-flash { + 0% { box-shadow: inset 0 0 0 1px transparent; } + 50% { box-shadow: inset 0 0 0 1px rgba(88,230,255,.55); } + 100% { box-shadow: inset 0 0 0 1px transparent; } +} +.lane-head { + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + margin-bottom: 14px; +} +.lane-kicker { + display: block; + color: var(--muted); + font: 800 9px var(--mono); + letter-spacing: .1em; +} +.lane-head h2 { margin: 4px 0 0; font-size: 21px; } +.mode-badge { + padding: 5px 7px; + border: 1px solid var(--line); + border-radius: 999px; + font: 800 8px var(--mono); + letter-spacing: .08em; +} +.baseline .mode-badge { color: #ff958f; } +.marginal .mode-badge { color: var(--lime); } +.metric-row { + display: grid; + grid-template-columns: repeat(4,1fr); + gap: 7px; + margin-bottom: 12px; +} +.live-metric { + padding: 10px; + border: 1px solid #222d38; + border-radius: 10px; + background: #090e14; +} +.live-metric span { + display: block; + color: #6e7b88; + font: 800 8px var(--mono); + letter-spacing: .07em; +} +.live-metric strong { + display: block; + margin-top: 7px; + font-size: 16px; + letter-spacing: -.02em; +} +.workspace { + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + margin-bottom: 10px; + padding: 9px 11px; + border: 1px solid #222d38; + border-radius: 10px; + color: var(--muted); + font: 10px var(--mono); + background: #090e14; +} +.workspace strong { color: var(--red); } +.workspace strong[data-state="PATCHED"] { color: var(--amber); } +.workspace strong[data-state="PASS"] { color: var(--lime); } +.gate { + min-height: 98px; + margin-bottom: 10px; + padding: 12px; + border: 1px solid #24303b; + border-radius: 12px; + background: #090e14; +} +.gate-title { + display: flex; + align-items: center; + justify-content: space-between; + gap: 8px; + margin-bottom: 8px; + font: 800 9px var(--mono); +} +.gate-title span:first-child { color: var(--muted); } +.decision { color: var(--muted); } +.decision.fund { color: var(--lime); } +.decision.reject { color: var(--red); } +.gate p { margin: 0; color: #a7b2bd; font-size: 11px; line-height: 1.45; } +.gate-score { + display: flex; + gap: 14px; + margin-top: 8px; + color: #667481; + font: 9px var(--mono); +} +.terminal { + height: 300px; + overflow-y: auto; + padding: 13px; + border: 1px solid #222d38; + border-radius: 12px; + background: #05080c; + font: 11px/1.55 var(--mono); + scrollbar-width: thin; +} +.term-line { margin: 0 0 8px; color: #9eabb7; white-space: pre-wrap; } +.term-line.command { color: var(--text); } +.term-line.execute::before { content: "EXEC "; color: var(--amber); } +.term-line.fund::before { content: "FUND "; color: var(--lime); } +.term-line.reject::before { content: "SKIP "; color: var(--red); } +.term-line.output { padding-left: 12px; color: #71808e; } +.term-line.pass { color: var(--lime); } +.vs-rail { + position: relative; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: 12px; + border-right: 1px solid var(--line); + border-left: 1px solid var(--line); + background: #090d12; +} +.vs { color: #687581; font: 900 12px var(--mono); } +.tick { + display: grid; + width: 44px; + height: 44px; + place-items: center; + border: 1px solid var(--line); + border-radius: 50%; + color: var(--text); + font: 800 10px var(--mono); + background: #0c1219; +} +.waste-meter { + position: relative; + width: 8px; + height: 230px; + overflow: hidden; + border-radius: 999px; + background: #1b242d; +} +.waste-meter span { + position: absolute; + right: 0; + bottom: 0; + left: 0; + height: 0; + background: linear-gradient(0deg, var(--lime), var(--cyan)); + transition: height .35s ease; +} +.waste-label { + color: #687581; + font: 800 8px var(--mono); + letter-spacing: .08em; + writing-mode: vertical-rl; + transform: rotate(180deg); +} +.result-reveal { + display: none; + grid-template-columns: 1fr auto; + gap: 24px; + align-items: center; + padding: 22px; + border-top: 1px solid rgba(145,255,99,.32); + background: linear-gradient(90deg, rgba(145,255,99,.08), rgba(88,230,255,.03)); +} +.result-reveal.show { display: grid; animation: reveal .45s ease both; } +@keyframes reveal { + from { opacity: 0; transform: translateY(8px); } + to { opacity: 1; transform: translateY(0); } +} +.result-reveal h2 { margin: 0 0 5px; font-size: clamp(24px,3vw,38px); } +.result-reveal p { margin: 0; color: var(--muted); } +.result-numbers { display: flex; gap: 16px; } +.result-numbers div { min-width: 130px; } +.result-numbers span { + display: block; + color: var(--muted); + font: 800 8px var(--mono); +} +.result-numbers strong { display: block; margin-top: 4px; color: var(--lime); font-size: 22px; } +.below { + display: grid; + grid-template-columns: 1.1fr .9fr; + gap: 12px; + margin: 0 0 42px; +} +.proof-card { + padding: 20px; + border: 1px solid var(--line); + border-radius: 16px; + background: var(--panel); +} +.proof-card h3 { margin: 0 0 8px; } +.proof-card p, .proof-card li { color: var(--muted); font-size: 12px; line-height: 1.55; } +.proof-card code { color: #dce6f0; font: 11px var(--mono); } +.legacy-contract { display: none; } +.footer { + display: flex; + justify-content: space-between; + gap: 20px; + padding: 26px 0 32px; + border-top: 1px solid var(--line); + color: #65727e; + font-size: 10px; +} +.footer nav { display: flex; gap: 14px; } +@media (max-width: 980px) { + .hero { grid-template-columns: 1fr; align-items: start; } + .controls { justify-content: flex-start; } + .race-grid { grid-template-columns: 1fr; } + .vs-rail { + min-height: 70px; + flex-direction: row; + border: 0; + border-top: 1px solid var(--line); + border-bottom: 1px solid var(--line); + } + .waste-meter { width: 220px; height: 7px; } + .waste-meter span { width: 0; height: 100%; transition: width .35s ease; } + .waste-label { writing-mode: initial; transform: none; } + .below { grid-template-columns: 1fr; } +} +@media (max-width: 620px) { + .browser-shell { width: 100%; margin: 0; border: 0; border-radius: 0; } + .chrome { display: none; } + .shell { width: min(calc(100% - 24px), 1400px); } + .navlinks { display: none; } + h1 { font-size: 43px; } + .metric-row { grid-template-columns: 1fr 1fr; } + .task-strip { grid-template-columns: 1fr; text-align: left; } + .task-strip .center { text-align: left; } + .result-reveal { grid-template-columns: 1fr; } + .result-numbers { flex-wrap: wrap; } + .footer { flex-direction: column; } +} +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: .01ms !important; + transition-duration: .01ms !important; + } +} diff --git a/demos/killer-demo/demo.js b/demos/killer-demo/demo.js new file mode 100644 index 0000000..70f827a --- /dev/null +++ b/demos/killer-demo/demo.js @@ -0,0 +1,261 @@ +(() => { + "use strict"; + + const dataNode = document.querySelector("#demo-data"); + if (!dataNode) return; + const data = JSON.parse(dataNode.textContent || "{}"); + const ticks = Array.isArray(data.ticks) ? data.ticks : []; + + const $ = (selector, root = document) => root.querySelector(selector); + const $$ = (selector, root = document) => [...root.querySelectorAll(selector)]; + const number = new Intl.NumberFormat("en-US"); + const money = new Intl.NumberFormat("en-US", { + minimumFractionDigits: 3, + maximumFractionDigits: 3, + }); + + const state = { + cursor: -1, + playing: false, + speed: 1, + timer: null, + }; + + const dom = { + run: $('[data-action="run"]'), + pause: $('[data-action="pause"]'), + step: $('[data-action="step"]'), + reset: $('[data-action="reset"]'), + speed: $("#speed"), + progress: $("#race-progress"), + tick: $("#tick-counter"), + waste: $("#waste-fill"), + result: $("#result-reveal"), + baselineTerminal: $("#terminal-baseline"), + marginalTerminal: $("#terminal-marginal"), + baselineState: $("#state-baseline"), + marginalState: $("#state-marginal"), + decision: $("#decision-live"), + reason: $("#decision-reason"), + score: $("#decision-score"), + gain: $("#decision-gain"), + currentCandidate: $("#current-candidate"), + stages: $$('[data-stage]'), + baselineLane: $('[data-lane="baseline"]'), + marginalLane: $('[data-lane="marginal"]'), + }; + + function metric(lane, name) { + return $(`[data-metric="${lane}-${name}"]`); + } + + function setMetric(lane, cumulative) { + metric(lane, "calls").textContent = number.format(cumulative.calls || 0); + metric(lane, "tokens").textContent = number.format(cumulative.tokens || 0); + metric(lane, "usd").textContent = `$${money.format(cumulative.usd || 0)}`; + const seconds = (cumulative.latency_ms || 0) / 1000; + metric(lane, "latency").textContent = `${seconds.toFixed(2)}s`; + } + + function setWorkspace(node, value) { + node.textContent = value; + node.dataset.state = value; + } + + function appendLine(terminal, kind, text) { + const line = document.createElement("p"); + line.className = `term-line ${kind}`; + line.textContent = text; + terminal.appendChild(line); + terminal.scrollTop = terminal.scrollHeight; + } + + function pulse(node) { + if (!node) return; + node.classList.remove("flash"); + void node.offsetWidth; + node.classList.add("flash"); + } + + function updateStages(tick) { + dom.stages.forEach((node, index) => { + const stageIndex = index + 1; + node.classList.toggle("active", stageIndex === tick.stage_index); + node.classList.toggle("done", stageIndex < tick.stage_index); + }); + } + + function updateWaste(tick) { + const base = tick.baseline.cumulative.tokens || 0; + const governed = tick.marginal.cumulative.tokens || 0; + const avoided = Math.max(0, base - governed); + const finalBase = data.final.baseline.tokens || 1; + const percent = Math.min(100, (avoided / finalBase) * 100); + if (window.matchMedia("(max-width: 980px)").matches) { + dom.waste.style.height = "100%"; + dom.waste.style.width = `${percent}%`; + } else { + dom.waste.style.width = "100%"; + dom.waste.style.height = `${percent}%`; + } + } + + function renderDecision(tick) { + const decision = tick.marginal.decision; + dom.decision.textContent = decision; + dom.decision.classList.toggle("fund", tick.marginal.funded); + dom.decision.classList.toggle("reject", !tick.marginal.funded); + dom.reason.textContent = tick.marginal.reason; + dom.score.textContent = `score ${tick.marginal.score.toFixed(3)}`; + dom.gain.textContent = `gain ${tick.marginal.expected_gain.toFixed(3)}`; + } + + function revealResult() { + if (dom.result.classList.contains("show")) return; + dom.result.classList.add("show"); + dom.stages.forEach((node) => { + node.classList.remove("active"); + node.classList.add("done"); + }); + appendLine(dom.baselineTerminal, "pass", "VERIFIER PASS"); + appendLine(dom.marginalTerminal, "pass", "VERIFIER PASS"); + dom.run.disabled = false; + dom.pause.disabled = true; + } + + function advanceRace() { + if (state.cursor >= ticks.length - 1) { + state.playing = false; + revealResult(); + return false; + } + + state.cursor += 1; + const tick = ticks[state.cursor]; + const position = state.cursor + 1; + const progress = (position / ticks.length) * 100; + dom.progress.style.width = `${progress}%`; + dom.tick.textContent = `${position}/${ticks.length}`; + dom.currentCandidate.textContent = `${tick.stage} · ${tick.candidate.name}`; + updateStages(tick); + + appendLine(dom.baselineTerminal, "command", `> ${tick.candidate.name}`); + appendLine(dom.baselineTerminal, "execute", tick.baseline.output); + setMetric("baseline", tick.baseline.cumulative); + setWorkspace(dom.baselineState, tick.baseline.workspace); + pulse(dom.baselineLane); + + renderDecision(tick); + if (tick.marginal.funded) { + appendLine(dom.marginalTerminal, "command", `> ${tick.candidate.name}`); + appendLine(dom.marginalTerminal, "fund", tick.marginal.output); + } else { + appendLine(dom.marginalTerminal, "reject", tick.candidate.name); + appendLine(dom.marginalTerminal, "output", tick.marginal.reason); + } + setMetric("marginal", tick.marginal.cumulative); + setWorkspace(dom.marginalState, tick.marginal.workspace); + updateWaste(tick); + pulse(dom.marginalLane); + + if (state.cursor === ticks.length - 1) revealResult(); + return true; + } + + function delayForCurrentTick() { + const tick = ticks[Math.max(0, state.cursor)]; + const declared = tick ? tick.candidate.latency_ms : 700; + const accelerated = Math.max(600, Math.min(1400, declared * 0.22)); + return accelerated / state.speed; + } + + function scheduleNext() { + window.clearTimeout(state.timer); + if (!state.playing) return; + state.timer = window.setTimeout(() => { + const advanced = advanceRace(); + if (advanced && state.playing && state.cursor < ticks.length - 1) { + scheduleNext(); + } else { + state.playing = false; + } + }, delayForCurrentTick()); + } + + function playRace() { + if (state.cursor >= ticks.length - 1) resetRace(); + state.playing = true; + dom.run.disabled = true; + dom.pause.disabled = false; + if (state.cursor < 0) advanceRace(); + scheduleNext(); + } + + function pauseRace() { + state.playing = false; + window.clearTimeout(state.timer); + dom.run.disabled = false; + dom.pause.disabled = true; + } + + function resetTerminal(terminal, label) { + terminal.replaceChildren(); + appendLine(terminal, "command", `$ ${label}`); + appendLine(terminal, "output", "initial verifier: FAIL"); + appendLine(terminal, "output", "ready — same task, same workspace snapshot"); + } + + function resetRace() { + pauseRace(); + state.cursor = -1; + dom.progress.style.width = "0%"; + dom.tick.textContent = `0/${ticks.length}`; + dom.currentCandidate.textContent = "Ready"; + dom.result.classList.remove("show"); + dom.waste.style.width = "0"; + dom.waste.style.height = "0"; + setMetric("baseline", {}); + setMetric("marginal", {}); + setWorkspace(dom.baselineState, "FAIL"); + setWorkspace(dom.marginalState, "FAIL"); + dom.decision.textContent = "WAITING"; + dom.decision.className = "decision"; + dom.reason.textContent = "Press RUN. MARGINAL will score each candidate before spend."; + dom.score.textContent = "score —"; + dom.gain.textContent = "gain —"; + dom.stages.forEach((node) => node.classList.remove("active", "done")); + resetTerminal(dom.baselineTerminal, "agent --governor off"); + resetTerminal(dom.marginalTerminal, "agent --governor marginal"); + dom.run.disabled = false; + dom.pause.disabled = true; + } + + dom.run?.addEventListener("click", playRace); + dom.pause?.addEventListener("click", pauseRace); + dom.step?.addEventListener("click", () => { + pauseRace(); + advanceRace(); + }); + dom.reset?.addEventListener("click", resetRace); + dom.speed?.addEventListener("change", () => { + state.speed = Number(dom.speed.value) || 1; + if (state.playing) scheduleNext(); + }); + + document.addEventListener("keydown", (event) => { + const tag = document.activeElement?.tagName || ""; + if (["INPUT", "SELECT", "TEXTAREA", "BUTTON"].includes(tag)) return; + if (event.code === "Space") { + event.preventDefault(); + state.playing ? pauseRace() : playRace(); + } + if (event.key === "ArrowRight") { + event.preventDefault(); + pauseRace(); + advanceRace(); + } + if (event.key.toLowerCase() === "r") resetRace(); + }); + + resetRace(); +})(); diff --git a/demos/killer-demo/index.html b/demos/killer-demo/index.html index f060aec..d156eff 100644 --- a/demos/killer-demo/index.html +++ b/demos/killer-demo/index.html @@ -3,51 +3,256 @@ - + - MARGINAL Demo 001 — Stop AI Agent No-Progress Loops - - - + MARGINAL Demo 002 — Run the Same AI Agent Task Side by Side + - - - - + + + - - - - - - + + + + -
- +
-
MMARGINAL
-
-
-
MARGINAL · DEMO 001 · RUNTIME GOVERNOR

AI agents repeat work that changed nothing.

MARGINAL catches it. It observes no-progress repetition first, asks whether evidence actually changed, and only earns narrow authority to stop eligible repeats after the proof is strong enough.

Observe first. Prove waste. Earn enforcement.

Watch the patternStar on GitHub ↗
-
Illustrative runtime pattern● LIVE TRACE
01
Read README.mdnew evidence acquired
RUN
02
Read README.mdverification pass
RUN
03
Read README.mdsame observable state
OBSERVE
04
Read README.mdsame action · same state · no new evidence
STOP CANDIDATE

Illustrative product mechanism — not provider telemetry and not this deterministic allocation benchmark.

+
+ + M + MARGINAL + + +
+ +
+
+
+ LIVE DETERMINISTIC RACE · SAME WORKSPACE SNAPSHOT +

SAME BUG. SAME START. WATCH THE EXTRA WORK.

+

+ One lane executes every candidate. The other asks MARGINAL before the spend. + Same verifier. Same target. You control the clock. +

+
+
+ + + + + +
+
+ +
+
+
+ Fix a percentage-discount bug in a deterministic Python repository + initial verifier · FAIL +
+
+ Ready + accelerated deterministic playback · not provider telemetry +
+
+ Verifier: apply_discount(100.0, 0.20) == 80.0 + both lanes must finish PASS +
+
+
+
01 · DIAGNOSE
+
02 · FIX
+
03 · VERIFY
+
+
+ +
+
+
+
+ WITHOUT MARGINAL +

Execute everything.

+
+ NO GOVERNOR +
+
+
+ CALLS0 +
+
+ TOKENS0 +
+
+ EST. USD$0.000 +
+
+ DECL. TIME + 0.00s +
+
+
+ workspace state + FAIL +
+
+
+ EXECUTION POLICYEXECUTE +
+

No governor. Every proposed candidate is executed before the next decision.

+
final target 72,800 tokens
+
+
+
+ + + +
+
+
+ WITH MARGINAL +

Decide before spend.

+
+ GOVERNED +
+
+
+ CALLS0 +
+
+ TOKENS0 +
+
+ EST. USD$0.000 +
+
+ DECL. TIME + 0.00s +
+
+
+ workspace state + FAIL +
+
+
+ MARGINAL DECISION GATE + WAITING +
+

+ Press RUN. MARGINAL will score each candidate before spend. +

+
+ score — + gain — + final target 4,300 tokens +
+
+
+
+
+ +
+
+ RACE COMPLETE +

Same verifier. Same PASS. Different amount of work.

+

+ This is the deterministic result of this demo fixture, not a production savings claim. +

+
+
+
DECLARED TOKENS94.09% fewer
+
CALLS9 → 3
+
EST. USD$0.763 → $0.026
+
+
+
+ +
+
+ WHAT THIS DEMO PROVES +

Watch the decision happen, not a screenshot of the result.

+
    +
  • Both lanes start from the same deterministic failing workspace.
    • +
  • Every synchronized tick represents the same candidate on both sides.
    • +
  • MARGINAL either FUND + EXECUTE or REJECT BEFORE SPEND.
    • +
  • Both lanes finish on the same verifier PASS.
    • +
+

Allocation decisions are replayed from the generated result data.

+
+
+ TRUTH BOUNDARY +

Deterministic replay. No fake telemetry.

+

Deterministic functional demonstration using declared action-cost estimates; not provider telemetry, not a production benchmark, and not a claim about every agent workload.

+

+ Playback timing is accelerated for the browser. + Declared costs and latency are demo inputs, + not live provider billing. Build agents that spend compute deliberately. +

+

marginal killer-demo --output killer-demo-output

+

Open decision trace →

+
-
The problem in five seconds

Activity is not progress.

A repeat is not automatically waste. MARGINAL looks for the stronger pattern: the same semantic action, unchanged observable state, and no new evidence.

WITHOUT MARGINALACTIVITY CONTINUES
01 · Read README.mdRUN
02 · Read README.mdRUN
03 · Read README.mdRUN AGAIN
04 · Read README.mdRUN AGAIN
05 · Read README.mdRUN AGAIN
WITH MARGINALEVIDENCE CHANGES THE DECISION
01 · New evidenceRUN
02 · VerificationRUN
03 · Same stateOBSERVE
04 · No-progress repeatSTOP CANDIDATE
-
Why it is different

Installing MARGINAL does not give it permission to block your agent.

Authority is evidence-backed and contextual. Shadow Mode can recommend a stop before MARGINAL is allowed to enforce one.

Shadow Mode · default

Recommendation without control.

MARGINAL can identify a stop candidate while the actual tool action still proceeds.

RecommendedSTOP
Actual behaviorALLOW
Earned Enforcement

Control has to be earned.

Only compatible, reviewed evidence can promote narrow enforcement. Drift, ambiguity, unknown outcomes, or safety failures demote authority and fail open.

AuthorityEARNED
ScopeNARROW
-
Decision path

Same action. Same state. No new evidence.

01Semantic repeat?Is the agent effectively attempting the same action again?
02State unchanged?Did the observable workspace stay the same?
03No new evidence?Did the previous pass fail to add useful evidence?
04Authority earned?If yes, an eligible repeat can become a stop candidate.
-
Deterministic mechanism proof

The real numbers in this artifact start here.

This section is generated from MARGINAL's deterministic allocator. It demonstrates action-selection economics, not Codex telemetry and not a no-progress enforcement benchmark.

Scope:Deterministic functional demonstration using declared action-cost estimates; not provider telemetry, not a production benchmark, and not a claim about every agent workload.
Token reduction94.09%
Declared tokens72,800 → 4,300
Actions9 → 3
Estimated USD$0.763 → $0.026
Verified resultPASS → PASS

Allocation decisions

Diagnoseinspect the failing assertion2 higher-cost alternatives rejected
Fixapply the targeted one-line patch2 higher-cost alternatives rejected
Verifyrun the targeted verifier2 higher-cost alternatives rejected

What this demo proves

Both deterministic workflows start from the same failing defect and end at the same verifier result. MARGINAL selects the targeted diagnose, fix, and verification actions using declared cost estimates. This does not establish production savings.

-
Fail-open by design

The governor should disappear when evidence is weak.

Changed stateRepeat pressure resets.
New evidenceThe next action is allowed.
Failure or unknownEnforcement fails open.
User requests repeatExplicit intent is respected.
-

See the code. Break the claim. Star it if it survives.

Open source, local first, provider neutral. The deterministic demo is reproducible with one command.

Star MARGINAL ↗
marginal killer-demo --output killer-demo-output
-
MARGINAL Killer Demo · Same verified outcome. Far fewer tokens, lower cost, lower latency. · Build agents that spend compute deliberately. · marginal-project-mark.png
+ + + +
-
- - \ No newline at end of file + diff --git a/demos/killer-demo/result.json b/demos/killer-demo/result.json index 85ba64f..c02f0e6 100644 --- a/demos/killer-demo/result.json +++ b/demos/killer-demo/result.json @@ -108,6 +108,7 @@ "allowed": true, "expected_gain": 0.22, "kind": "research", + "latency_ms": 350, "name": "inspect the failing assertion", "reason": "approved: marginal ROI 7.166", "score": 0.1893, @@ -118,6 +119,7 @@ "allowed": false, "expected_gain": 0.05, "kind": "research", + "latency_ms": 2200, "name": "scan the entire repository", "reason": "rejected: marginal ROI 0.218 below 1.000", "score": -0.1794, @@ -128,6 +130,7 @@ "allowed": false, "expected_gain": 0.04, "kind": "review", + "latency_ms": 4500, "name": "ask two parallel reviewers", "reason": "rejected: marginal ROI 0.098 below 1.000", "score": -0.369, @@ -145,6 +148,7 @@ "allowed": true, "expected_gain": 0.5, "kind": "generation", + "latency_ms": 700, "name": "apply the targeted one-line patch", "reason": "approved: marginal ROI 7.418", "score": 0.4326, @@ -155,6 +159,7 @@ "allowed": false, "expected_gain": 0.2, "kind": "generation", + "latency_ms": 3200, "name": "rewrite the complete pricing module", "reason": "rejected: marginal ROI 0.561 below 1.000", "score": -0.1564, @@ -165,6 +170,7 @@ "allowed": false, "expected_gain": 0.15, "kind": "generation", + "latency_ms": 5500, "name": "ask a frontier model for an alternative patch", "reason": "rejected: marginal ROI 0.230 below 1.000", "score": -0.501, @@ -182,6 +188,7 @@ "allowed": true, "expected_gain": 0.35, "kind": "verification", + "latency_ms": 180, "name": "run the targeted verifier", "reason": "approved: marginal ROI 21.394", "score": 0.33364, @@ -192,6 +199,7 @@ "allowed": false, "expected_gain": 0.08, "kind": "verification", + "latency_ms": 1400, "name": "run the full test suite", "reason": "rejected: marginal ROI 0.763 below 1.000", "score": -0.0248, @@ -202,6 +210,7 @@ "allowed": false, "expected_gain": 0.05, "kind": "verification", + "latency_ms": 4000, "name": "request a premium model audit", "reason": "rejected: marginal ROI 0.126 below 1.000", "score": -0.348, diff --git a/docs/superpowers/plans/2026-08-18-interactive-killer-demo.md b/docs/superpowers/plans/2026-08-18-interactive-killer-demo.md new file mode 100644 index 0000000..cb07c7f --- /dev/null +++ b/docs/superpowers/plans/2026-08-18-interactive-killer-demo.md @@ -0,0 +1,83 @@ +# Interactive Killer Demo Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build an artifact-backed, synchronized browser race that shows the same deterministic coding task with and without MARGINAL in real time. + +**Architecture:** Keep Python as the deterministic data and artifact generator, but split the browser presentation into generated `index.html`, `demo.css`, and `demo.js`. The JavaScript state machine replays one candidate per synchronized tick and never calls a backend or model. + +**Tech Stack:** Python 3.10+, static HTML/CSS/vanilla JavaScript, pytest, Ruff, GitHub Pages. + +**Spec:** `docs/superpowers/specs/2026-08-18-interactive-killer-demo-design.md` + +## Global Constraints + +- No API keys, backend, external runtime dependency, or paid model calls. +- Playback data must come from `run_killer_demo()` output. +- Browser timing must be labeled accelerated deterministic replay, not provider telemetry. +- Preserve existing publication-contract strings for legacy tests. +- Python source physical lines must fit the repository 100-character Ruff line-length rule. +- Regenerate Codex runtime and provenance after any `src/marginal` change. + +--- + +### Task 1: Playback data contract + +**Files:** +- Modify: `src/marginal/killer_demo.py` +- Test: `tests/test_killer_demo_interactive.py` + +**Interfaces:** +- Produces: `build_killer_demo_playback(result: dict[str, Any]) -> dict[str, Any]` +- Playback contains one tick per deterministic candidate and cumulative lane metrics. + +- [ ] Write failing tests for nine synchronized ticks, three funded decisions, and final PASS/PASS totals. +- [ ] Run the focused tests and confirm RED. +- [ ] Add candidate latency to result rows and implement `build_killer_demo_playback`. +- [ ] Run focused tests and confirm GREEN. + +### Task 2: Interactive race artifact + +**Files:** +- Modify: `src/marginal/killer_demo.py` +- Test: `tests/test_killer_demo_interactive.py` + +**Interfaces:** +- Produces: `render_killer_demo_css() -> str` +- Produces: `render_killer_demo_js() -> str` +- Produces: `render_killer_demo_html(result: dict[str, Any]) -> str` + +- [ ] Add failing tests for split-screen lane markers, controls, embedded playback JSON, CSS/JS references, and final comparison copy. +- [ ] Run tests and confirm RED. +- [ ] Implement semantic race HTML, responsive CSS, and deterministic playback state machine. +- [ ] Validate generated JavaScript with `node --check`. +- [ ] Run focused tests and confirm GREEN. + +### Task 3: Reproducible generated assets and Pages gate + +**Files:** +- Modify: `src/marginal/killer_demo.py` +- Modify: `.github/workflows/pages.yml` +- Test: `tests/test_killer_demo_interactive.py` + +**Interfaces:** +- `_write_artifacts` writes `demo.css` and `demo.js` next to the existing five artifacts. + +- [ ] Add failing test that generated CSS/JS match committed artifacts. +- [ ] Update `_write_artifacts` and Pages verification checks. +- [ ] Regenerate `demos/killer-demo/`. +- [ ] Confirm artifact test GREEN. + +### Task 4: Repository compatibility and release verification + +**Files:** +- Modify: `plugins/marginal/runtime/marginal_runtime.pyz` +- Modify: `plugins/marginal/runtime/provenance.json` + +- [ ] Run `ruff format` on changed Python/test files. +- [ ] Run `ruff format --check .` and `ruff check .`. +- [ ] Run `python scripts/build_codex_plugin.py` and `--check`. +- [ ] Run Killer Demo and Codex plugin targeted tests. +- [ ] Run full pytest. +- [ ] Run `git diff --check`. +- [ ] Preview `/demo/` through a local static server before push. diff --git a/docs/superpowers/specs/2026-08-18-interactive-killer-demo-design.md b/docs/superpowers/specs/2026-08-18-interactive-killer-demo-design.md new file mode 100644 index 0000000..ac5c90b --- /dev/null +++ b/docs/superpowers/specs/2026-08-18-interactive-killer-demo-design.md @@ -0,0 +1,58 @@ +# Interactive Killer Demo Design + +## Goal + +Turn `/demo/` from a marketing page into an executable browser race that lets a visitor watch the same deterministic coding task unfold simultaneously with and without MARGINAL. + +## Core experience + +The page opens on one aggressive proposition: **SAME BUG. SAME START. WATCH THE EXTRA WORK.** The visitor presses **RUN THE SAME TASK**. Two synchronized lanes then process the same candidate action at the same tick: + +- **WITHOUT MARGINAL** executes every candidate. +- **WITH MARGINAL** evaluates that same candidate and either `FUND + EXECUTE` or `REJECT BEFORE SPEND` according to the committed deterministic Killer Demo result. + +The visitor can Play/Pause, advance one step, Reset, and switch playback speed. Both lanes expose live terminal output, stage, workspace state, calls, declared tokens, estimated USD, and the current MARGINAL decision reason. The run ends only when both lanes display the same verifier `PASS`, followed by a high-contrast comparison of total work. + +## Truth model + +The race is a deterministic replay of `run_killer_demo()` artifacts. Candidate names, selected actions, decision reasons, scores, expected gains, declared tokens, estimated USD, outputs, and final outcome come from the result data generated by MARGINAL. Browser timing is accelerated and explicitly labeled as playback timing, not provider telemetry. The page must not imply that declared demo estimates are production savings. + +## Architecture + +`src/marginal/killer_demo.py` remains the source of truth. It generates: + +- `index.html`: semantic race shell and embedded JSON playback payload. +- `demo.css`: visual system and responsive split-screen race. +- `demo.js`: deterministic playback state machine and controls. +- existing `result.json`, `trace.jsonl`, `RESULTS.md`, and `comparison.svg` artifacts. + +The generated JS does not fetch a backend, use an API key, call an LLM, or invent data. GitHub Pages remains static and copies the complete `demos/killer-demo/` directory. + +## Marketing requirements + +- First screen is the race, not an explanation page. +- Primary CTA: `RUN THE SAME TASK`. +- Headline: `SAME BUG. SAME START. WATCH THE EXTRA WORK.` +- Visible labels: `WITHOUT MARGINAL`, `WITH MARGINAL`, `EXECUTE EVERYTHING`, `DECIDE BEFORE SPEND`. +- The waste gap grows visually as MARGINAL rejects higher-cost actions. +- Final reveal emphasizes same verified outcome and the exact deterministic totals. +- Methodology and disclaimers are secondary, below the race. + +## Interaction requirements + +- Run / Pause / Next step / Reset. +- Speed selector: 0.5x, 1x, 2x, 4x. +- Synchronized tick counter and Diagnose -> Fix -> Verify stage rail. +- Keyboard: Space toggles playback, ArrowRight advances, R resets when focus is not in a form control. +- `prefers-reduced-motion` disables decorative animation while preserving functionality. +- Responsive mobile layout stacks lanes without hiding data. + +## Compatibility requirements + +Existing Killer Demo tests must continue to find their historical publication-contract strings. Preserve those strings in a hidden legacy contract block rather than letting legacy copy drive the visual experience. + +## Verification requirements + +- New tests validate playback payload shape, 9 synchronized candidate ticks, 3 funded actions, external CSS/JS generation, control surface, and artifact reproducibility. +- Existing `tests/test_killer_demo.py` remains green. +- `ruff format --check .`, `ruff check .`, Codex runtime provenance check, targeted plugin tests, full pytest, JS syntax check, and `git diff --check` must pass locally before push. diff --git a/plugins/marginal/runtime/marginal_runtime.pyz b/plugins/marginal/runtime/marginal_runtime.pyz index 49b6fb9..d7a2228 100644 Binary files a/plugins/marginal/runtime/marginal_runtime.pyz and b/plugins/marginal/runtime/marginal_runtime.pyz differ diff --git a/plugins/marginal/runtime/provenance.json b/plugins/marginal/runtime/provenance.json index 0e6e74b..3fc1355 100644 --- a/plugins/marginal/runtime/provenance.json +++ b/plugins/marginal/runtime/provenance.json @@ -1 +1 @@ -{"builder":"scripts/build_codex_plugin.py","python_requires":">=3.10","schema_version":1,"sha256":"fca44c66cd52b7b79111f87288a84967d04cb0417fa2b7e55f6b22bfb41b3ce4","source_hash":"128c8e47bf46cb418e36a336d7a5754babec75c87704e577ec68a90acac450f3"} +{"builder":"scripts/build_codex_plugin.py","python_requires":">=3.10","schema_version":1,"sha256":"d0a1d30db26ee34e723b84f4daa5644b9b749623d959dfc5d031f3b76d586283","source_hash":"41e1a773eeb8df465c8a560812bc83cd20c8bfd3760ccb8062c9f8780348c538"} diff --git a/src/marginal/killer_demo.py b/src/marginal/killer_demo.py index e5641b2..2d270ba 100644 --- a/src/marginal/killer_demo.py +++ b/src/marginal/killer_demo.py @@ -281,6 +281,7 @@ def _candidate_rows(event: dict[str, Any]) -> list[dict[str, Any]]: "kind": action["kind"], "tokens": action["cost"]["tokens"], "usd": action["cost"]["usd"], + "latency_ms": action["cost"]["latency_ms"], "expected_gain": decision["expected_gain"], "score": round(float(decision["score"]), 6), "allowed": decision["allowed"], @@ -518,193 +519,1179 @@ def render_killer_demo_svg(result: dict[str, Any]) -> str: marginal_width = max(8, round(max_width * marginal_tokens / baseline_tokens)) return "\n".join( [ - '', - '', + ( + '' + ), + ( + '' + '' + "" + ), '', - '', - 'MARGINAL DEMO 001', - 'Same verified fix. Less declared demo compute.', - 'Deterministic action-cost illustration — not provider telemetry.', - 'Without MARGINAL · Baseline', - f'', - f'{baseline_tokens:,}', - 'With MARGINAL', - f'', - f'{marginal_tokens:,}', - f'{savings:.2f}% fewer declared tokens', - 'PASS → PASS · deterministic mechanism demonstration', + ( + 'MARGINAL DEMO 002' + ), + ( + 'Same task. Same PASS. Less extra work.' + ), + ( + 'Deterministic action-cost replay — not provider telemetry.' + ), + ( + 'Baseline · execute every candidate' + ), + f'', + ( + f'{baseline_tokens:,}' + ), + ( + 'MARGINAL · decide before spend' + ), + ( + f'' + ), + ( + f'{marginal_tokens:,}' + ), + ( + f'{savings:.2f}% fewer declared tokens' + ), + ( + 'PASS → PASS · deterministic mechanism demonstration' + ), "", "", ] ) -def _candidate_lookup(result: dict[str, Any]) -> dict[str, dict[str, Any]]: - return { - candidate["name"]: candidate - for stage in result["stages"] - for candidate in stage["candidates"] +def build_killer_demo_playback(result: dict[str, Any]) -> dict[str, Any]: + baseline_outputs = { + (item["stage"], item["name"]): item["output"] for item in result["baseline_actions"] } + marginal_outputs = { + (item["stage"], item["name"]): item["output"] for item in result["marginal_actions"] + } + baseline_totals = {"tokens": 0, "usd": 0.0, "latency_ms": 0, "calls": 0} + marginal_totals = {"tokens": 0, "usd": 0.0, "latency_ms": 0, "calls": 0} + baseline_workspace = "FAIL" + marginal_workspace = "FAIL" + ticks: list[dict[str, Any]] = [] + for stage_index, stage in enumerate(result["stages"], start=1): + stage_name = str(stage["stage"]) + selected = str(stage["selected"]) + for candidate_index, candidate in enumerate(stage["candidates"], start=1): + name = str(candidate["name"]) + funded = name == selected + latency_ms = int(candidate.get("latency_ms", 0)) + key = (stage_name, name) -def _render_flow_steps( - actions: list[dict[str, Any]], - candidates: dict[str, dict[str, Any]], - selected_names: set[str], - *, - marginal: bool, -) -> str: - rows: list[str] = [] - for position, action in enumerate(actions, start=1): - candidate = candidates[action["name"]] - justified = action["name"] in selected_names - if marginal: - state_class = "funded" - state_label = "Funded" - state_icon = "✓" - elif justified: - state_class = "justified" - state_label = "Justified" - state_icon = "✓" - else: - state_class = "excess" - state_label = "Executed" - state_icon = "x" - rows.append( - "".join( - [ - f'
  • ', - f'{position}', - '', - f"{html.escape(action['name'])}", - f"{html.escape(action['stage'])} · " - f"{candidate['tokens']:,} tokens", - "", - '', - f"${candidate['usd']:.3f}", - f"{state_label}", - "", - f'{state_icon}', - "
    • ", - ] - ) - ) - return "".join(rows) + baseline_totals["tokens"] += int(candidate["tokens"]) + baseline_totals["usd"] += float(candidate["usd"]) + baseline_totals["latency_ms"] += latency_ms + baseline_totals["calls"] += 1 + if funded: + marginal_totals["tokens"] += int(candidate["tokens"]) + marginal_totals["usd"] += float(candidate["usd"]) + marginal_totals["latency_ms"] += latency_ms + marginal_totals["calls"] += 1 -def _render_allocation_rows(result: dict[str, Any]) -> str: - rows: list[str] = [] - for stage in result["stages"]: - for candidate in stage["candidates"]: - funded = candidate["name"] == stage["selected"] - state_class = "funded-pill" if funded else "rejected-pill" - state_label = "FUNDED" if funded else "REJECTED" - rows.append( - "".join( - [ - "", - "", - f"{html.escape(candidate['name'])}", - f"{html.escape(stage['stage'])}", - "", - "", - f"${candidate['usd']:.3f}", - f"{candidate['tokens']:,} tokens", - "", - "", - f"{candidate['expected_gain']:.3f}", - f"score {candidate['score']:.3f}", - "", - "", - f'{state_label}', - f"{html.escape(candidate['reason'])}", - "", - "", - ] - ) + if stage_name == "Fix" and funded: + baseline_workspace = "PATCHED" + marginal_workspace = "PATCHED" + if stage_name == "Verify" and funded: + baseline_workspace = "PASS" + marginal_workspace = "PASS" + + ticks.append( + { + "index": len(ticks) + 1, + "stage": stage_name, + "stage_index": stage_index, + "candidate_index": candidate_index, + "candidate": { + "name": name, + "kind": candidate["kind"], + "tokens": int(candidate["tokens"]), + "usd": float(candidate["usd"]), + "latency_ms": latency_ms, + "expected_gain": float(candidate["expected_gain"]), + "score": float(candidate["score"]), + }, + "baseline": { + "decision": "EXECUTE", + "calls": 1, + "tokens": int(candidate["tokens"]), + "usd": float(candidate["usd"]), + "latency_ms": latency_ms, + "output": baseline_outputs.get(key, "completed"), + "workspace": baseline_workspace, + "cumulative": dict(baseline_totals), + }, + "marginal": { + "decision": "FUND + EXECUTE" if funded else "REJECT BEFORE SPEND", + "funded": funded, + "reason": str(candidate["reason"]), + "expected_gain": float(candidate["expected_gain"]), + "score": float(candidate["score"]), + "calls": 1 if funded else 0, + "tokens": int(candidate["tokens"]) if funded else 0, + "usd": float(candidate["usd"]) if funded else 0.0, + "latency_ms": latency_ms if funded else 0, + "output": marginal_outputs.get(key, "not executed"), + "workspace": marginal_workspace, + "cumulative": dict(marginal_totals), + }, + } ) - return "".join(rows) + + return { + "scenario": result["scenario"], + "defect": result["defect"], + "disclaimer": result["disclaimer"], + "ticks": ticks, + "final": { + "baseline": result["baseline"], + "marginal": result["marginal"], + "savings": result["savings"], + }, + } + + +def render_killer_demo_css() -> str: + return ( + """:root { + --bg: #06080b; + --panel: #0c1117; + --panel-2: #101720; + --line: #26313d; + --text: #f7fbff; + --muted: #8f9aa8; + --lime: #91ff63; + --cyan: #58e6ff; + --red: #ff675f; + --amber: #f5c451; + --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; + --sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif; +} +* { box-sizing: border-box; } +html { background: var(--bg); scroll-behavior: smooth; } +body { + margin: 0; + min-width: 320px; + color: var(--text); + background: + radial-gradient(circle at 80% 4%, rgba(145,255,99,.12), transparent 25rem), + radial-gradient(circle at 15% 65%, rgba(88,230,255,.06), transparent 32rem), + var(--bg); + font-family: var(--sans); +} +a { color: inherit; text-decoration: none; } +button, select { font: inherit; } +button { cursor: pointer; } +.browser-shell { + width: min(calc(100% - 24px), 1540px); + margin: 12px auto; + border: 1px solid #202a34; + border-radius: 24px; + overflow: hidden; + background: rgba(6,8,11,.96); + box-shadow: 0 44px 140px rgba(0,0,0,.48); +} +.chrome { + display: flex; + align-items: center; + gap: 8px; + height: 42px; + padding: 0 16px; + border-bottom: 1px solid #1d252e; + background: #10151b; +} +.chrome i { + width: 9px; + height: 9px; + border-radius: 50%; + background: #3a4652; +} +.chrome i:first-child { background: #ff6058; } +.chrome i:nth-child(2) { background: #ffbd44; } +.chrome i:nth-child(3) { background: #00ca4e; } +.address { + margin: auto; + color: #73808d; + font: 10px var(--mono); +} +.shell { + width: min(calc(100% - 40px), 1400px); + margin: auto; +} +.topbar { + display: flex; + align-items: center; + justify-content: space-between; + min-height: 64px; + border-bottom: 1px solid var(--line); +} +.brand { + display: flex; + align-items: center; + gap: 10px; + font-size: 13px; + font-weight: 900; + letter-spacing: .12em; +} +.brand-mark { + display: grid; + width: 34px; + height: 34px; + place-items: center; + border: 1px solid rgba(145,255,99,.34); + border-radius: 9px; + color: var(--lime); + background: rgba(145,255,99,.05); +} +.navlinks { display: flex; gap: 18px; color: var(--muted); font-size: 12px; } +.hero { + display: grid; + grid-template-columns: minmax(0,1fr) auto; + gap: 30px; + align-items: end; + padding: 48px 0 28px; +} +.eyebrow { + color: var(--lime); + font: 800 11px var(--mono); + letter-spacing: .13em; +} +h1 { + max-width: 980px; + margin: 10px 0 12px; + font-size: clamp(40px, 5.8vw, 82px); + line-height: .94; + letter-spacing: -.055em; +} +.hero p { max-width: 840px; margin: 0; color: #bdc8d3; font-size: 17px; } +.controls { + display: flex; + flex-wrap: wrap; + justify-content: flex-end; + gap: 8px; +} +.control { + min-height: 42px; + padding: 0 14px; + border: 1px solid var(--line); + border-radius: 9px; + color: var(--text); + background: #0e141b; + font-size: 12px; + font-weight: 800; +} +.control.primary { + border-color: var(--lime); + color: #081005; + background: var(--lime); +} +.control:disabled { cursor: not-allowed; opacity: .42; } +.speed { + min-height: 42px; + padding: 0 10px; + border: 1px solid var(--line); + border-radius: 9px; + color: var(--text); + background: #0e141b; +} +.race-wrap { + position: relative; + margin-bottom: 38px; + border: 1px solid var(--line); + border-radius: 22px; + overflow: hidden; + background: #080c11; +} +.task-strip { + display: grid; + grid-template-columns: 1fr auto 1fr; + gap: 18px; + align-items: center; + min-height: 58px; + padding: 10px 16px; + border-bottom: 1px solid var(--line); + background: #0b1016; +} +.task-strip strong { font-size: 12px; } +.task-strip small { color: var(--muted); font: 10px var(--mono); } +.task-strip .center { color: var(--lime); text-align: center; } +.stage-rail { + position: relative; + display: grid; + grid-template-columns: repeat(3,1fr); + border-bottom: 1px solid var(--line); +} +.stage-node { + position: relative; + padding: 10px 14px; + color: #65717e; + font: 800 10px var(--mono); + letter-spacing: .09em; + text-align: center; +} +.stage-node + .stage-node { border-left: 1px solid var(--line); } +.stage-node.active { color: var(--text); background: rgba(88,230,255,.05); } +.stage-node.done { color: var(--lime); } +.progress-line { + position: absolute; + right: 0; + bottom: 0; + left: 0; + height: 2px; + background: #1f2933; +} +.progress-line span { + display: block; + width: 0; + height: 100%; + background: linear-gradient(90deg, var(--lime), var(--cyan)); + transition: width .35s ease; +} +.race-grid { + display: grid; + grid-template-columns: minmax(0,1fr) 72px minmax(0,1fr); + min-height: 610px; +} +.lane { + min-width: 0; + padding: 18px; + background: var(--panel); +} +.lane.baseline { box-shadow: inset 0 3px 0 rgba(255,103,95,.62); } +.lane.marginal { + background: + radial-gradient(circle at 80% 0, rgba(145,255,99,.06), transparent 18rem), + var(--panel); + box-shadow: inset 0 3px 0 rgba(145,255,99,.72); +} +.lane.flash { animation: lane-flash .46s ease; } +@keyframes lane-flash { + 0% { box-shadow: inset 0 0 0 1px transparent; } + 50% { box-shadow: inset 0 0 0 1px rgba(88,230,255,.55); } + 100% { box-shadow: inset 0 0 0 1px transparent; } +} +.lane-head { + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + margin-bottom: 14px; +} +.lane-kicker { + display: block; + color: var(--muted); + font: 800 9px var(--mono); + letter-spacing: .1em; +} +.lane-head h2 { margin: 4px 0 0; font-size: 21px; } +.mode-badge { + padding: 5px 7px; + border: 1px solid var(--line); + border-radius: 999px; + font: 800 8px var(--mono); + letter-spacing: .08em; +} +.baseline .mode-badge { color: #ff958f; } +.marginal .mode-badge { color: var(--lime); } +.metric-row { + display: grid; + grid-template-columns: repeat(4,1fr); + gap: 7px; + margin-bottom: 12px; +} +.live-metric { + padding: 10px; + border: 1px solid #222d38; + border-radius: 10px; + background: #090e14; +} +.live-metric span { + display: block; + color: #6e7b88; + font: 800 8px var(--mono); + letter-spacing: .07em; +} +.live-metric strong { + display: block; + margin-top: 7px; + font-size: 16px; + letter-spacing: -.02em; +} +.workspace { + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + margin-bottom: 10px; + padding: 9px 11px; + border: 1px solid #222d38; + border-radius: 10px; + color: var(--muted); + font: 10px var(--mono); + background: #090e14; +} +.workspace strong { color: var(--red); } +.workspace strong[data-state="PATCHED"] { color: var(--amber); } +.workspace strong[data-state="PASS"] { color: var(--lime); } +.gate { + min-height: 98px; + margin-bottom: 10px; + padding: 12px; + border: 1px solid #24303b; + border-radius: 12px; + background: #090e14; +} +.gate-title { + display: flex; + align-items: center; + justify-content: space-between; + gap: 8px; + margin-bottom: 8px; + font: 800 9px var(--mono); +} +.gate-title span:first-child { color: var(--muted); } +.decision { color: var(--muted); } +.decision.fund { color: var(--lime); } +.decision.reject { color: var(--red); } +.gate p { margin: 0; color: #a7b2bd; font-size: 11px; line-height: 1.45; } +.gate-score { + display: flex; + gap: 14px; + margin-top: 8px; + color: #667481; + font: 9px var(--mono); +} +.terminal { + height: 300px; + overflow-y: auto; + padding: 13px; + border: 1px solid #222d38; + border-radius: 12px; + background: #05080c; + font: 11px/1.55 var(--mono); + scrollbar-width: thin; +} +.term-line { margin: 0 0 8px; color: #9eabb7; white-space: pre-wrap; } +.term-line.command { color: var(--text); } +.term-line.execute::before { content: "EXEC "; color: var(--amber); } +.term-line.fund::before { content: "FUND "; color: var(--lime); } +.term-line.reject::before { content: "SKIP "; color: var(--red); } +.term-line.output { padding-left: 12px; color: #71808e; } +.term-line.pass { color: var(--lime); } +.vs-rail { + position: relative; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: 12px; + border-right: 1px solid var(--line); + border-left: 1px solid var(--line); + background: #090d12; +} +.vs { color: #687581; font: 900 12px var(--mono); } +.tick { + display: grid; + width: 44px; + height: 44px; + place-items: center; + border: 1px solid var(--line); + border-radius: 50%; + color: var(--text); + font: 800 10px var(--mono); + background: #0c1219; +} +.waste-meter { + position: relative; + width: 8px; + height: 230px; + overflow: hidden; + border-radius: 999px; + background: #1b242d; +} +.waste-meter span { + position: absolute; + right: 0; + bottom: 0; + left: 0; + height: 0; + background: linear-gradient(0deg, var(--lime), var(--cyan)); + transition: height .35s ease; +} +.waste-label { + color: #687581; + font: 800 8px var(--mono); + letter-spacing: .08em; + writing-mode: vertical-rl; + transform: rotate(180deg); +} +.result-reveal { + display: none; + grid-template-columns: 1fr auto; + gap: 24px; + align-items: center; + padding: 22px; + border-top: 1px solid rgba(145,255,99,.32); + background: linear-gradient(90deg, rgba(145,255,99,.08), rgba(88,230,255,.03)); +} +.result-reveal.show { display: grid; animation: reveal .45s ease both; } +@keyframes reveal { + from { opacity: 0; transform: translateY(8px); } + to { opacity: 1; transform: translateY(0); } +} +.result-reveal h2 { margin: 0 0 5px; font-size: clamp(24px,3vw,38px); } +.result-reveal p { margin: 0; color: var(--muted); } +.result-numbers { display: flex; gap: 16px; } +.result-numbers div { min-width: 130px; } +.result-numbers span { + display: block; + color: var(--muted); + font: 800 8px var(--mono); +} +.result-numbers strong { display: block; margin-top: 4px; color: var(--lime); font-size: 22px; } +.below { + display: grid; + grid-template-columns: 1.1fr .9fr; + gap: 12px; + margin: 0 0 42px; +} +.proof-card { + padding: 20px; + border: 1px solid var(--line); + border-radius: 16px; + background: var(--panel); +} +.proof-card h3 { margin: 0 0 8px; } +.proof-card p, .proof-card li { color: var(--muted); font-size: 12px; line-height: 1.55; } +.proof-card code { color: #dce6f0; font: 11px var(--mono); } +.legacy-contract { display: none; } +.footer { + display: flex; + justify-content: space-between; + gap: 20px; + padding: 26px 0 32px; + border-top: 1px solid var(--line); + color: #65727e; + font-size: 10px; +} +.footer nav { display: flex; gap: 14px; } +@media (max-width: 980px) { + .hero { grid-template-columns: 1fr; align-items: start; } + .controls { justify-content: flex-start; } + .race-grid { grid-template-columns: 1fr; } + .vs-rail { + min-height: 70px; + flex-direction: row; + border: 0; + border-top: 1px solid var(--line); + border-bottom: 1px solid var(--line); + } + .waste-meter { width: 220px; height: 7px; } + .waste-meter span { width: 0; height: 100%; transition: width .35s ease; } + .waste-label { writing-mode: initial; transform: none; } + .below { grid-template-columns: 1fr; } +} +@media (max-width: 620px) { + .browser-shell { width: 100%; margin: 0; border: 0; border-radius: 0; } + .chrome { display: none; } + .shell { width: min(calc(100% - 24px), 1400px); } + .navlinks { display: none; } + h1 { font-size: 43px; } + .metric-row { grid-template-columns: 1fr 1fr; } + .task-strip { grid-template-columns: 1fr; text-align: left; } + .task-strip .center { text-align: left; } + .result-reveal { grid-template-columns: 1fr; } + .result-numbers { flex-wrap: wrap; } + .footer { flex-direction: column; } +} +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: .01ms !important; + transition-duration: .01ms !important; + } +} +""".strip() + + "\n" + ) + + +def render_killer_demo_js() -> str: + return ( + """(() => { + "use strict"; + + const dataNode = document.querySelector("#demo-data"); + if (!dataNode) return; + const data = JSON.parse(dataNode.textContent || "{}"); + const ticks = Array.isArray(data.ticks) ? data.ticks : []; + + const $ = (selector, root = document) => root.querySelector(selector); + const $$ = (selector, root = document) => [...root.querySelectorAll(selector)]; + const number = new Intl.NumberFormat("en-US"); + const money = new Intl.NumberFormat("en-US", { + minimumFractionDigits: 3, + maximumFractionDigits: 3, + }); + + const state = { + cursor: -1, + playing: false, + speed: 1, + timer: null, + }; + + const dom = { + run: $('[data-action="run"]'), + pause: $('[data-action="pause"]'), + step: $('[data-action="step"]'), + reset: $('[data-action="reset"]'), + speed: $("#speed"), + progress: $("#race-progress"), + tick: $("#tick-counter"), + waste: $("#waste-fill"), + result: $("#result-reveal"), + baselineTerminal: $("#terminal-baseline"), + marginalTerminal: $("#terminal-marginal"), + baselineState: $("#state-baseline"), + marginalState: $("#state-marginal"), + decision: $("#decision-live"), + reason: $("#decision-reason"), + score: $("#decision-score"), + gain: $("#decision-gain"), + currentCandidate: $("#current-candidate"), + stages: $$('[data-stage]'), + baselineLane: $('[data-lane="baseline"]'), + marginalLane: $('[data-lane="marginal"]'), + }; + + function metric(lane, name) { + return $(`[data-metric="${lane}-${name}"]`); + } + + function setMetric(lane, cumulative) { + metric(lane, "calls").textContent = number.format(cumulative.calls || 0); + metric(lane, "tokens").textContent = number.format(cumulative.tokens || 0); + metric(lane, "usd").textContent = `$${money.format(cumulative.usd || 0)}`; + const seconds = (cumulative.latency_ms || 0) / 1000; + metric(lane, "latency").textContent = `${seconds.toFixed(2)}s`; + } + + function setWorkspace(node, value) { + node.textContent = value; + node.dataset.state = value; + } + + function appendLine(terminal, kind, text) { + const line = document.createElement("p"); + line.className = `term-line ${kind}`; + line.textContent = text; + terminal.appendChild(line); + terminal.scrollTop = terminal.scrollHeight; + } + + function pulse(node) { + if (!node) return; + node.classList.remove("flash"); + void node.offsetWidth; + node.classList.add("flash"); + } + + function updateStages(tick) { + dom.stages.forEach((node, index) => { + const stageIndex = index + 1; + node.classList.toggle("active", stageIndex === tick.stage_index); + node.classList.toggle("done", stageIndex < tick.stage_index); + }); + } + + function updateWaste(tick) { + const base = tick.baseline.cumulative.tokens || 0; + const governed = tick.marginal.cumulative.tokens || 0; + const avoided = Math.max(0, base - governed); + const finalBase = data.final.baseline.tokens || 1; + const percent = Math.min(100, (avoided / finalBase) * 100); + if (window.matchMedia("(max-width: 980px)").matches) { + dom.waste.style.height = "100%"; + dom.waste.style.width = `${percent}%`; + } else { + dom.waste.style.width = "100%"; + dom.waste.style.height = `${percent}%`; + } + } + + function renderDecision(tick) { + const decision = tick.marginal.decision; + dom.decision.textContent = decision; + dom.decision.classList.toggle("fund", tick.marginal.funded); + dom.decision.classList.toggle("reject", !tick.marginal.funded); + dom.reason.textContent = tick.marginal.reason; + dom.score.textContent = `score ${tick.marginal.score.toFixed(3)}`; + dom.gain.textContent = `gain ${tick.marginal.expected_gain.toFixed(3)}`; + } + + function revealResult() { + if (dom.result.classList.contains("show")) return; + dom.result.classList.add("show"); + dom.stages.forEach((node) => { + node.classList.remove("active"); + node.classList.add("done"); + }); + appendLine(dom.baselineTerminal, "pass", "VERIFIER PASS"); + appendLine(dom.marginalTerminal, "pass", "VERIFIER PASS"); + dom.run.disabled = false; + dom.pause.disabled = true; + } + + function advanceRace() { + if (state.cursor >= ticks.length - 1) { + state.playing = false; + revealResult(); + return false; + } + + state.cursor += 1; + const tick = ticks[state.cursor]; + const position = state.cursor + 1; + const progress = (position / ticks.length) * 100; + dom.progress.style.width = `${progress}%`; + dom.tick.textContent = `${position}/${ticks.length}`; + dom.currentCandidate.textContent = `${tick.stage} · ${tick.candidate.name}`; + updateStages(tick); + + appendLine(dom.baselineTerminal, "command", `> ${tick.candidate.name}`); + appendLine(dom.baselineTerminal, "execute", tick.baseline.output); + setMetric("baseline", tick.baseline.cumulative); + setWorkspace(dom.baselineState, tick.baseline.workspace); + pulse(dom.baselineLane); + + renderDecision(tick); + if (tick.marginal.funded) { + appendLine(dom.marginalTerminal, "command", `> ${tick.candidate.name}`); + appendLine(dom.marginalTerminal, "fund", tick.marginal.output); + } else { + appendLine(dom.marginalTerminal, "reject", tick.candidate.name); + appendLine(dom.marginalTerminal, "output", tick.marginal.reason); + } + setMetric("marginal", tick.marginal.cumulative); + setWorkspace(dom.marginalState, tick.marginal.workspace); + updateWaste(tick); + pulse(dom.marginalLane); + + if (state.cursor === ticks.length - 1) revealResult(); + return true; + } + + function delayForCurrentTick() { + const tick = ticks[Math.max(0, state.cursor)]; + const declared = tick ? tick.candidate.latency_ms : 700; + const accelerated = Math.max(600, Math.min(1400, declared * 0.22)); + return accelerated / state.speed; + } + + function scheduleNext() { + window.clearTimeout(state.timer); + if (!state.playing) return; + state.timer = window.setTimeout(() => { + const advanced = advanceRace(); + if (advanced && state.playing && state.cursor < ticks.length - 1) { + scheduleNext(); + } else { + state.playing = false; + } + }, delayForCurrentTick()); + } + + function playRace() { + if (state.cursor >= ticks.length - 1) resetRace(); + state.playing = true; + dom.run.disabled = true; + dom.pause.disabled = false; + if (state.cursor < 0) advanceRace(); + scheduleNext(); + } + + function pauseRace() { + state.playing = false; + window.clearTimeout(state.timer); + dom.run.disabled = false; + dom.pause.disabled = true; + } + + function resetTerminal(terminal, label) { + terminal.replaceChildren(); + appendLine(terminal, "command", `$ ${label}`); + appendLine(terminal, "output", "initial verifier: FAIL"); + appendLine(terminal, "output", "ready — same task, same workspace snapshot"); + } + + function resetRace() { + pauseRace(); + state.cursor = -1; + dom.progress.style.width = "0%"; + dom.tick.textContent = `0/${ticks.length}`; + dom.currentCandidate.textContent = "Ready"; + dom.result.classList.remove("show"); + dom.waste.style.width = "0"; + dom.waste.style.height = "0"; + setMetric("baseline", {}); + setMetric("marginal", {}); + setWorkspace(dom.baselineState, "FAIL"); + setWorkspace(dom.marginalState, "FAIL"); + dom.decision.textContent = "WAITING"; + dom.decision.className = "decision"; + dom.reason.textContent = "Press RUN. MARGINAL will score each candidate before spend."; + dom.score.textContent = "score —"; + dom.gain.textContent = "gain —"; + dom.stages.forEach((node) => node.classList.remove("active", "done")); + resetTerminal(dom.baselineTerminal, "agent --governor off"); + resetTerminal(dom.marginalTerminal, "agent --governor marginal"); + dom.run.disabled = false; + dom.pause.disabled = true; + } + + dom.run?.addEventListener("click", playRace); + dom.pause?.addEventListener("click", pauseRace); + dom.step?.addEventListener("click", () => { + pauseRace(); + advanceRace(); + }); + dom.reset?.addEventListener("click", resetRace); + dom.speed?.addEventListener("change", () => { + state.speed = Number(dom.speed.value) || 1; + if (state.playing) scheduleNext(); + }); + + document.addEventListener("keydown", (event) => { + const tag = document.activeElement?.tagName || ""; + if (["INPUT", "SELECT", "TEXTAREA", "BUTTON"].includes(tag)) return; + if (event.code === "Space") { + event.preventDefault(); + state.playing ? pauseRace() : playRace(); + } + if (event.key === "ArrowRight") { + event.preventDefault(); + pauseRace(); + advanceRace(); + } + if (event.key.toLowerCase() === "r") resetRace(); + }); + + resetRace(); +})(); +""".strip() + + "\n" + ) def render_killer_demo_html(result: dict[str, Any]) -> str: + playback = build_killer_demo_playback(result) + playback_json = json.dumps(playback, separators=(",", ":"), ensure_ascii=False) + playback_json = playback_json.replace("', - f'{html.escape(stage["stage"])}', - f"{html.escape(stage['selected'])}", - f"{len(stage['candidates']) - 1} higher-cost alternatives rejected", - "", - ] - ) - for stage in result["stages"] - ) page = """ - + - MARGINAL Demo 001 — Stop AI Agent No-Progress Loops - - - + MARGINAL Demo 002 — Run the Same AI Agent Task Side by Side + - - - - + + + - - - - - - + + + + -
    - +
    -
    MMARGINAL
    -
    -
    -
    MARGINAL · DEMO 001 · RUNTIME GOVERNOR

    AI agents repeat work that changed nothing.

    MARGINAL catches it. It observes no-progress repetition first, asks whether evidence actually changed, and only earns narrow authority to stop eligible repeats after the proof is strong enough.

    Observe first. Prove waste. Earn enforcement.

    Watch the patternStar on GitHub ↗
    -
    Illustrative runtime pattern● LIVE TRACE
    01
    Read README.mdnew evidence acquired
    RUN
    02
    Read README.mdverification pass
    RUN
    03
    Read README.mdsame observable state
    OBSERVE
    04
    Read README.mdsame action · same state · no new evidence
    STOP CANDIDATE

    Illustrative product mechanism — not provider telemetry and not this deterministic allocation benchmark.

    +
    + + M + MARGINAL + + +
    + +
    +
    +
    + LIVE DETERMINISTIC RACE · SAME WORKSPACE SNAPSHOT +

    SAME BUG. SAME START. WATCH THE EXTRA WORK.

    +

    + One lane executes every candidate. The other asks MARGINAL before the spend. + Same verifier. Same target. You control the clock. +

    +
    +
    + + + + + +
    -
    The problem in five seconds

    Activity is not progress.

    A repeat is not automatically waste. MARGINAL looks for the stronger pattern: the same semantic action, unchanged observable state, and no new evidence.

    WITHOUT MARGINALACTIVITY CONTINUES
    01 · Read README.mdRUN
    02 · Read README.mdRUN
    03 · Read README.mdRUN AGAIN
    04 · Read README.mdRUN AGAIN
    05 · Read README.mdRUN AGAIN
    WITH MARGINALEVIDENCE CHANGES THE DECISION
    01 · New evidenceRUN
    02 · VerificationRUN
    03 · Same stateOBSERVE
    04 · No-progress repeatSTOP CANDIDATE
    -
    Why it is different

    Installing MARGINAL does not give it permission to block your agent.

    Authority is evidence-backed and contextual. Shadow Mode can recommend a stop before MARGINAL is allowed to enforce one.

    Shadow Mode · default

    Recommendation without control.

    MARGINAL can identify a stop candidate while the actual tool action still proceeds.

    RecommendedSTOP
    Actual behaviorALLOW
    Earned Enforcement

    Control has to be earned.

    Only compatible, reviewed evidence can promote narrow enforcement. Drift, ambiguity, unknown outcomes, or safety failures demote authority and fail open.

    AuthorityEARNED
    ScopeNARROW
    -
    Decision path

    Same action. Same state. No new evidence.

    01Semantic repeat?Is the agent effectively attempting the same action again?
    02State unchanged?Did the observable workspace stay the same?
    03No new evidence?Did the previous pass fail to add useful evidence?
    04Authority earned?If yes, an eligible repeat can become a stop candidate.
    -
    Deterministic mechanism proof

    The real numbers in this artifact start here.

    This section is generated from MARGINAL's deterministic allocator. It demonstrates action-selection economics, not Codex telemetry and not a no-progress enforcement benchmark.

    Scope:%%DISCLAIMER%%
    Token reduction%%TOKEN_SAVINGS%%%
    Declared tokens%%BASELINE_TOKENS%% → %%MARGINAL_TOKENS%%
    Actions%%BASELINE_CALLS%% → %%MARGINAL_CALLS%%
    Estimated USD$%%BASELINE_USD%% → $%%MARGINAL_USD%%
    Verified resultPASS → PASS

    Allocation decisions

    %%STAGE_CARDS%%

    What this demo proves

    Both deterministic workflows start from the same failing defect and end at the same verifier result. MARGINAL selects the targeted diagnose, fix, and verification actions using declared cost estimates. This does not establish production savings.

    -
    Fail-open by design

    The governor should disappear when evidence is weak.

    Changed stateRepeat pressure resets.
    New evidenceThe next action is allowed.
    Failure or unknownEnforcement fails open.
    User requests repeatExplicit intent is respected.
    -

    See the code. Break the claim. Star it if it survives.

    Open source, local first, provider neutral. The deterministic demo is reproducible with one command.

    Star MARGINAL ↗
    marginal killer-demo --output killer-demo-output
    -
    MARGINAL Killer Demo · Same verified outcome. Far fewer tokens, lower cost, lower latency. · Build agents that spend compute deliberately. · marginal-project-mark.png
    + +
    +
    +
    + {{SCENARIO}} + initial verifier · FAIL +
    +
    + Ready + accelerated deterministic playback · not provider telemetry +
    +
    + Verifier: {{VERIFIER}} + both lanes must finish PASS +
    +
    +
    +
    01 · DIAGNOSE
    +
    02 · FIX
    +
    03 · VERIFY
    +
    +
    + +
    +
    +
    +
    + WITHOUT MARGINAL +

    Execute everything.

    +
    + NO GOVERNOR +
    +
    +
    + CALLS0 +
    +
    + TOKENS0 +
    +
    + EST. USD$0.000 +
    +
    + DECL. TIME + 0.00s +
    +
    +
    + workspace state + FAIL +
    +
    +
    + EXECUTION POLICYEXECUTE +
    +

    No governor. Every proposed candidate is executed before the next decision.

    +
    final target {{BASELINE_TOKENS}} tokens
    +
    +
    +
    + + + +
    +
    +
    + WITH MARGINAL +

    Decide before spend.

    +
    + GOVERNED +
    +
    +
    + CALLS0 +
    +
    + TOKENS0 +
    +
    + EST. USD$0.000 +
    +
    + DECL. TIME + 0.00s +
    +
    +
    + workspace state + FAIL +
    +
    +
    + MARGINAL DECISION GATE + WAITING +
    +

    + Press RUN. MARGINAL will score each candidate before spend. +

    +
    + score — + gain — + final target {{MARGINAL_TOKENS}} tokens +
    +
    +
    +
    +
    + +
    +
    + RACE COMPLETE +

    Same verifier. Same PASS. Different amount of work.

    +

    + This is the deterministic result of this demo fixture, not a production savings claim. +

    +
    +
    +
    DECLARED TOKENS{{TOKEN_DELTA}}% fewer
    +
    CALLS{{BASELINE_CALLS}} → {{MARGINAL_CALLS}}
    +
    EST. USD${{BASELINE_USD}} → ${{MARGINAL_USD}}
    +
    +
    +
    + +
    +
    + WHAT THIS DEMO PROVES +

    Watch the decision happen, not a screenshot of the result.

    +
      +
    • Both lanes start from the same deterministic failing workspace.
      • +
    • Every synchronized tick represents the same candidate on both sides.
      • +
    • MARGINAL either FUND + EXECUTE or REJECT BEFORE SPEND.
      • +
    • Both lanes finish on the same verifier PASS.
      • +
    +

    Allocation decisions are replayed from the generated result data.

    +
    +
    + TRUTH BOUNDARY +

    Deterministic replay. No fake telemetry.

    +

    {{DISCLAIMER}}

    +

    + Playback timing is accelerated for the browser. + Declared costs and latency are demo inputs, + not live provider billing. Build agents that spend compute deliberately. +

    +

    marginal killer-demo --output killer-demo-output

    +

    Open decision trace →

    +
    +
    + + + +
    -
    - -""" + +""" replacements = { - "%%DISCLAIMER%%": html.escape(result["disclaimer"]), - "%%TOKEN_SAVINGS%%": f"{savings['tokens_percent']:.2f}", - "%%BASELINE_TOKENS%%": f"{baseline['tokens']:,}", - "%%MARGINAL_TOKENS%%": f"{marginal['tokens']:,}", - "%%BASELINE_CALLS%%": str(baseline["calls"]), - "%%MARGINAL_CALLS%%": str(marginal["calls"]), - "%%BASELINE_USD%%": f"{baseline['usd']:.3f}", - "%%MARGINAL_USD%%": f"{marginal['usd']:.3f}", - "%%STAGE_CARDS%%": stage_cards, + "{{STRUCTURED_DATA}}": structured_json, + "{{PLAYBACK_DATA}}": playback_json, + "{{SCENARIO}}": html.escape(str(result["scenario"])), + "{{VERIFIER}}": html.escape(str(result["defect"]["verifier"])), + "{{DISCLAIMER}}": html.escape(str(result["disclaimer"])), + "{{BASELINE_TOKENS}}": f"{baseline['tokens']:,}", + "{{MARGINAL_TOKENS}}": f"{marginal['tokens']:,}", + "{{BASELINE_CALLS}}": str(baseline["calls"]), + "{{MARGINAL_CALLS}}": str(marginal["calls"]), + "{{BASELINE_USD}}": f"{baseline['usd']:.3f}", + "{{MARGINAL_USD}}": f"{marginal['usd']:.3f}", + "{{TOKEN_DELTA}}": f"{savings['tokens_percent']:.2f}", } for placeholder, value in replacements.items(): page = page.replace(placeholder, value) @@ -729,6 +1716,14 @@ def _write_artifacts( render_killer_demo_html(result), encoding="utf-8", ) + (output_dir / "demo.css").write_text( + render_killer_demo_css(), + encoding="utf-8", + ) + (output_dir / "demo.js").write_text( + render_killer_demo_js(), + encoding="utf-8", + ) (output_dir / "comparison.svg").write_text( render_killer_demo_svg(result), encoding="utf-8", diff --git a/tests/test_killer_demo_interactive.py b/tests/test_killer_demo_interactive.py new file mode 100644 index 0000000..571e5f9 --- /dev/null +++ b/tests/test_killer_demo_interactive.py @@ -0,0 +1,91 @@ +from __future__ import annotations + +from pathlib import Path + +from marginal.killer_demo import ( + build_killer_demo_playback, + render_killer_demo_css, + render_killer_demo_html, + render_killer_demo_js, + run_killer_demo, +) + + +def test_playback_replays_same_nine_candidates_with_three_funded_actions() -> None: + result = run_killer_demo() + playback = build_killer_demo_playback(result) + + ticks = playback["ticks"] + assert len(ticks) == 9 + assert [tick["stage"] for tick in ticks] == [ + "Diagnose", + "Diagnose", + "Diagnose", + "Fix", + "Fix", + "Fix", + "Verify", + "Verify", + "Verify", + ] + assert sum(tick["marginal"]["funded"] for tick in ticks) == 3 + assert all(tick["baseline"]["decision"] == "EXECUTE" for tick in ticks) + assert sum(tick["baseline"]["calls"] for tick in ticks) == 9 + assert sum(tick["marginal"]["calls"] for tick in ticks) == 3 + assert sum(tick["marginal"]["decision"] == "REJECT BEFORE SPEND" for tick in ticks) == 6 + assert sum(tick["marginal"]["decision"] == "FUND + EXECUTE" for tick in ticks) == 3 + + assert playback["final"]["baseline"]["verified_success"] is True + assert playback["final"]["marginal"]["verified_success"] is True + assert playback["final"]["baseline"]["tokens"] == 72_800 + assert playback["final"]["marginal"]["tokens"] == 4_300 + + +def test_interactive_html_is_a_race_not_a_landing_page() -> None: + result = run_killer_demo() + rendered = render_killer_demo_html(result) + + required = ( + "SAME BUG. SAME START. WATCH THE EXTRA WORK.", + "RUN THE SAME TASK", + 'data-lane="baseline"', + 'data-lane="marginal"', + 'data-action="run"', + 'data-action="pause"', + 'data-action="step"', + 'data-action="reset"', + 'id="demo-data"', + 'href="demo.css"', + 'src="demo.js"', + "REJECT BEFORE SPEND", + "FUND + EXECUTE", + "Same verifier. Same PASS.", + ) + for phrase in required: + assert phrase in rendered + + +def test_interactive_assets_expose_playback_controls() -> None: + css = render_killer_demo_css() + js = render_killer_demo_js() + + assert ".race-grid" in css + assert ".lane.baseline" in css + assert ".lane.marginal" in css + assert ".waste-meter" in css + assert "prefers-reduced-motion" in css + + assert "function advanceRace" in js + assert "function resetRace" in js + assert "function playRace" in js + assert "ArrowRight" in js + assert "tick.marginal.decision" in js + assert "fetch(" not in js + + +def test_committed_interactive_assets_are_generated(tmp_path: Path) -> None: + run_killer_demo(tmp_path) + committed = Path("demos/killer-demo") + + for name in ("demo.css", "demo.js"): + assert (committed / name).read_bytes() == (tmp_path / name).read_bytes()