feat: add /notes with two engineering write-ups and diagrams

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-03 19:21:00 +02:00
parent cc0d9bd9c2
commit 4eb663f42a
11 changed files with 992 additions and 4 deletions
@@ -0,0 +1,151 @@
+import * as React from "react";
+
+const MONO = "ui-monospace, monospace";
+
+type Box = {
+  readonly y: number;
+  readonly height: number;
+  readonly title: string;
+  readonly lines: readonly string[];
+  readonly tag: string;
+  readonly variant: "shell" | "core" | "chain";
+};
+
+const BOXES: readonly Box[] = [
+  {
+    y: 10,
+    height: 66,
+    title: "Detectors, one per chain (7)",
+    lines: ["index borrower positions, read state"],
+    tag: "shell: I/O",
+    variant: "shell",
+  },
+  {
+    y: 120,
+    height: 110,
+    title: "Pure domain crate",
+    lines: [
+      "health factor",
+      "fixed-point arithmetic",
+      "closed-form optimum, checked",
+      "against an exact swap engine",
+    ],
+    tag: "core: no I/O",
+    variant: "core",
+  },
+  {
+    y: 274,
+    height: 66,
+    title: "Submit shell",
+    lines: ["builds the transaction, sends it"],
+    tag: "shell: I/O",
+    variant: "shell",
+  },
+  {
+    y: 384,
+    height: 104,
+    title: "On-chain executor (Solidity)",
+    lines: [
+      "flash loan, liquidate, swap collateral,",
+      "repay. Reverts if the trade would",
+      "not be profitable.",
+    ],
+    tag: "atomic",
+    variant: "chain",
+  },
+];
+
+const ARROWS = [
+  { from: 76, label: "positions as data" },
+  { from: 230, label: "decision as data" },
+  { from: 340, label: "signed transaction" },
+] as const;
+
+const ARROW_LENGTH = 44;
+
+const boxClass = (variant: Box["variant"]): string =>
+  variant === "core"
+    ? "fill-surface stroke-accent"
+    : "fill-surface stroke-border-strong";
+
+export const CoreShellDiagram: React.FC = () => (
+  <svg
+    viewBox="0 0 480 500"
+    role="img"
+    aria-labelledby="core-title core-desc"
+    className="h-auto w-full"
+  >
+    <title id="core-title">Pure core, thin shells, on-chain executor</title>
+    <desc id="core-desc">
+      Per-chain detector shells read state and pass positions as plain data to a
+      pure domain crate. The core returns a decision as data to a submit shell,
+      which sends a transaction to the on-chain executor. The executor takes a
+      flash loan, liquidates, swaps collateral and repays, and reverts if the
+      trade would not be profitable.
+    </desc>
+    {BOXES.map((box) => (
+      <g key={box.title}>
+        <rect
+          x={20}
+          y={box.y}
+          width={440}
+          height={box.height}
+          rx={6}
+          className={boxClass(box.variant)}
+          strokeWidth={box.variant === "core" ? 2 : 1.5}
+          strokeDasharray={box.variant === "chain" ? "6 4" : undefined}
+        />
+        <text
+          x={36}
+          y={box.y + 24}
+          fontSize={15}
+          fontFamily={MONO}
+          className={box.variant === "core" ? "fill-accent" : "fill-current"}
+        >
+          {box.title}
+        </text>
+        {box.lines.map((line, index) => (
+          <text
+            key={line}
+            x={36}
+            y={box.y + 46 + index * 18}
+            fontSize={13}
+            fontFamily={MONO}
+            className="fill-muted"
+          >
+            {line}
+          </text>
+        ))}
+        <text
+          x={444}
+          y={box.y + 24}
+          fontSize={12}
+          fontFamily={MONO}
+          textAnchor="end"
+          className="fill-muted"
+        >
+          {box.tag}
+        </text>
+      </g>
+    ))}
+    {ARROWS.map((arrow) => (
+      <g key={arrow.label}>
+        <path
+          d={`M240 ${arrow.from + 2} v${ARROW_LENGTH - 8} m-5 -5 l5 5 l5 -5`}
+          className="stroke-border-strong"
+          fill="none"
+          strokeWidth={1.5}
+        />
+        <text
+          x={254}
+          y={arrow.from + ARROW_LENGTH / 2 + 4}
+          fontSize={12}
+          fontFamily={MONO}
+          className="fill-muted"
+        >
+          {arrow.label}
+        </text>
+      </g>
+    ))}
+  </svg>
+);
@@ -0,0 +1,115 @@
+import * as React from "react";
+
+const GATES = [
+  { title: "TDD gate", detail: "spec first, red before green" },
+  {
+    title: "Functional-style gate",
+    detail: "no methods, traits, &mut, unwrap",
+  },
+  { title: "Mutation gate", detail: "zero survivors, proof ledger" },
+  { title: "Coverage ratchet", detail: "fails when coverage drops" },
+] as const;
+
+const SPEEDS = [
+  { label: "changed lines: dev loop", width: 150 },
+  { label: "changed crates: pre-merge", width: 300 },
+  { label: "everything: merge gate", width: 440 },
+] as const;
+
+const GATE_HEIGHT = 52;
+const GATE_GAP = 20;
+const GATE_TOP = 10;
+const SPEEDS_TOP = 320;
+const SPEED_ROW = 42;
+
+export const GatePipelineDiagram: React.FC = () => (
+  <svg
+    viewBox="0 0 480 470"
+    role="img"
+    aria-labelledby="gate-title gate-desc"
+    className="h-auto w-full"
+  >
+    <title id="gate-title">The gate pipeline</title>
+    <desc id="gate-desc">
+      Four gates run in sequence: a TDD gate, a functional-style gate, a
+      mutation gate and a coverage ratchet. Below them, three scopes of
+      increasing size run the same gates: changed lines in the dev loop, changed
+      crates before merge, and everything at the merge gate.
+    </desc>
+    {GATES.map((gate, index) => {
+      const y = GATE_TOP + index * (GATE_HEIGHT + GATE_GAP);
+      return (
+        <g key={gate.title}>
+          <rect
+            x={20}
+            y={y}
+            width={440}
+            height={GATE_HEIGHT}
+            rx={6}
+            className="fill-surface stroke-accent"
+            strokeWidth={1.5}
+          />
+          <text
+            x={36}
+            y={y + 22}
+            fontSize={15}
+            fontFamily="ui-monospace, monospace"
+            className="fill-accent"
+          >
+            {gate.title}
+          </text>
+          <text
+            x={36}
+            y={y + 42}
+            fontSize={13}
+            fontFamily="ui-monospace, monospace"
+            className="fill-muted"
+          >
+            {gate.detail}
+          </text>
+          {index < GATES.length - 1 ? (
+            <path
+              d={`M240 ${y + GATE_HEIGHT + 2} v${GATE_GAP - 8} m-5 -5 l5 5 l5 -5`}
+              className="stroke-border-strong"
+              fill="none"
+              strokeWidth={1.5}
+            />
+          ) : null}
+        </g>
+      );
+    })}
+    <text
+      x={20}
+      y={SPEEDS_TOP - 12}
+      fontSize={13}
+      fontFamily="ui-monospace, monospace"
+      className="fill-muted"
+    >
+      same gates, three speeds
+    </text>
+    {SPEEDS.map((speed, index) => {
+      const y = SPEEDS_TOP + index * SPEED_ROW;
+      return (
+        <g key={speed.label}>
+          <text
+            x={20}
+            y={y + 14}
+            fontSize={14}
+            fontFamily="ui-monospace, monospace"
+            className="fill-current"
+          >
+            {speed.label}
+          </text>
+          <rect
+            x={20}
+            y={y + 22}
+            width={speed.width}
+            height={6}
+            rx={3}
+            className="fill-accent"
+          />
+        </g>
+      );
+    })}
+  </svg>
+);
@@ -0,0 +1,39 @@
+import * as React from "react";
+
+type WithChildren = { readonly children: React.ReactNode };
+
+export const NoteSection: React.FC<WithChildren> = ({ children }) => (
+  <h2 className="!mb-4 !mt-12 !text-2xl !leading-snug text-fg md:!text-3xl">
+    {children}
+  </h2>
+);
+
+export const NoteParagraph: React.FC<WithChildren> = ({ children }) => (
+  <p className="!mb-5 !text-base !leading-8 text-fg/85 md:!text-lg md:!leading-8">
+    {children}
+  </p>
+);
+
+export const NoteList: React.FC<WithChildren> = ({ children }) => (
+  <ul className="!mb-6 !ml-5 list-disc space-y-2 text-base leading-8 text-fg/85 marker:text-accent md:text-lg">
+    {children}
+  </ul>
+);
+
+export const NoteCode: React.FC<WithChildren> = ({ children }) => (
+  <code className="font-mono">{children}</code>
+);
+
+type NoteFigureProps = WithChildren & { readonly caption: string };
+
+export const NoteFigure: React.FC<NoteFigureProps> = ({
+  children,
+  caption,
+}) => (
+  <figure className="my-10 rounded-lg border border-border bg-surface p-5 md:p-8">
+    <div className="mx-auto max-w-md text-fg">{children}</div>
+    <figcaption className="mt-4 text-center font-mono text-xs text-muted">
+      {caption}
+    </figcaption>
+  </figure>
+);