@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-site-sizing/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: mdk-site-sizing
+description: >
+  Size an MDK deployment from a plain description of a site using measured
+  benchmark envelopes. Use when the task mentions "size a site", "how many
+  Workers", "capacity", "hardware for N miners", "sizing recommendation",
+  "deployment envelope", "devices per Worker", or turning benchmark results
+  into a Kernel/Worker/Gateway layout.
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.7.0"
+license: Apache-2.0
+---
+
+# Size an MDK site from a description
+
+Measured performance data turned into an Agent Skill that sizes an MDK
+deployment from a plain description of a site. Bar: the Skill's recommendations
+match the measured envelope on a held-out set of site descriptions.
+
+Do **not** invent CPU, RAM, devices-per-Worker, or pass/fail status. Parse the
+site, run the sizer, quote the matching envelope.
+
+## When to use
+
+| Situation                                           | Action     |
+| --------------------------------------------------- | ---------- |
+| "How many Workers for N miners on this host?"       | This skill |
+| "Size a site from this description"                 | This skill |
+| Turn `backend/tests/benchmark/results/*.json` into advice | Compile the envelope, then this skill |
+| Write `mdk.yaml` / `mdk run` after a size is agreed | Hand off to `mdk-deployment` |
+| Measure a new host | Point at the [capacity harness](../../../../../backend/tests/benchmark/README.md); do not guess |
+
+## Workflow
+
+Copy this checklist:
+
+```
+Task Progress:
+- [ ] 1. Parse the site description into facts
+- [ ] 2. Run size-site.mjs against the envelope (never skip)
+- [ ] 3. Present the script output as the recommendation
+- [ ] 4. If status is unmeasured or beyond-envelope, stop claiming support
+```
+
+### 1. Parse
+
+Extract facts matching this shape (or run `scripts/parse-site.mjs`):
+
+```json
+{
+  "devices": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "count": 80 }
+  ],
+  "deviceCount": 80,
+  "host": {
+    "tier": "edge | site-server | custom",
+    "cpuCoresPhysical": 16,
+    "ramGiB": 64,
+    "diskType": "nvme | sata | hdd | sd"
+  },
+  "kernels": 1,
+  "gateways": 1
+}
+```
+
+Worker `type` values are package names (`mdk-worker-whatsminer`,
+`mdk-worker-antminer`, `mdk-worker-avalon`). Map vendor prose (MicroBT,
+Bitmain, Canaan) onto those names. Default topology is **1 Kernel, 1 Gateway**.
+
+If a count or family is missing, leave it null. Do not fill gaps with a guess.
+
+### 2. Size (mandatory)
+
+From this skill directory. Never paste the operator's text into a shell
+command (not even inside double quotes: `$( )`, backticks and `"` still
+expand). Write it verbatim to a file with your file-writing tool, then pass the
+file:
+
+```bash
+node scripts/size-site.mjs --description-file site.txt --md
+# or, if you already wrote facts.json:
+node scripts/size-site.mjs facts.json --md
+```
+
+The script reads [`references/envelope.json`](./references/envelope.json) and
+prints the recommendation. That JSON is the measured envelope. Treat its
+`status`, Worker count, devices-per-Worker, and resource numbers as
+authoritative.
+
+Rebuild the envelope after a real harness run:
+
+```bash
+node scripts/compile-envelope.mjs --from <repo>/backend/tests/benchmark/results
+```
+
+Without committed harness reports, the envelope is compiled from
+[`eval/profiles/`](./eval/profiles/cap-100devices-2workers.json) (same schema
+as a harness profile). Label any quote from a `source: fixture` envelope as
+fixture data.
+
+### 3. Present
+
+Use the script's `--md` output, or the same table it renders: status, tier,
+devices, Workers, devices per Worker, Kernels, Gateways, matching profile,
+RSS, CPU, p99, supported-up-to (densest **green** profile on that mix and
+tier). Repeat the script's caveats verbatim.
+
+**Supported** means `status: green` inside the envelope. Amber is "little spare
+capacity", not a supported-up-to bound. `beyond-envelope` and `unmeasured` are
+not sizes: tell the operator to run the harness.
+
+### 4. Hand-off
+
+Once the operator accepts a green (or explicit amber) layout, use
+`mdk-deployment` to write `mdk.yaml` with that Worker count and device split.
+
+## Envelope rules (do not override)
+
+- Match on device-family set, then reference tier (`edge` / `site-server` /
+  `custom`). Custom profiles may fill a tier gap; they do not change the host
+  tier you report.
+- Covering profile = smallest profile with `deviceCount >= requested` at the
+  best pass/fail (`green` then `amber`). Worker count is
+  `ceil(requested / devices-per-Worker)` from that profile.
+- Resource numbers interpolate between the next-smaller green point and the
+  covering profile. Do not extrapolate past the last non-red point and call it
+  green.
+- Densest green on that mix+tier is `supportedUpTo`. A red profile is a
+  measured failure, not a layout to copy.
+- Unknown families (no profile in the envelope) → `unmeasured`.
+
+Full compile/lookup notes: [`references/envelope.md`](./references/envelope.md).
+
+## Held-out bar
+
+The bar is that the Skill's recommendations match the measured envelope on a
+held-out set of site descriptions. Prove it:
+
+```bash
+node scripts/compile-envelope.mjs
+node scripts/eval-held-out.mjs
+```
+
+[`eval/held-out.json`](./eval/held-out.json) is the held-out set: prose the
+train profiles never use as ids, expected windows read off the envelope.
+`eval-held-out.mjs` parses each description, sizes it, and exits 0 only when
+every case matches. Do not edit expected windows to make a bad recommendation
+pass; fix parse/size or add a measured profile.
+
+## Utility scripts
+
+| Script                 | Run                                                     |
+| ---------------------- | ------------------------------------------------------- |
+| `parse-site.mjs`       | `node scripts/parse-site.mjs < site.txt`                |
+| `size-site.mjs`        | `node scripts/size-site.mjs --description-file site.txt [--md]` |
+| `compile-envelope.mjs` | `node scripts/compile-envelope.mjs [--from <dir>]`      |
+| `eval-held-out.mjs`    | `node scripts/eval-held-out.mjs`                        |
+
+Execute these. Do not reimplement them in the conversation.

package/dist/skills/mdk-site-sizing/eval/held-out.json

@@ -0,0 +1,104 @@
+{
+  "bar": "the Skill's recommendations match the measured envelope on a held-out set of site descriptions.",
+  "note": "Descriptions are never the profile ids. Expected windows are read off the compiled envelope, not re-authored from the prose.",
+  "cases": [
+    {
+      "id": "edge-ten-whatsminer",
+      "description": "A single rack of ten Whatsminer M56S colocated with a small edge box: 4 physical cores, 8 GiB RAM, SATA SSD.",
+      "expected": {
+        "status": "green",
+        "tier": "edge",
+        "workerCount": 1,
+        "matchingProfileId": "cap-10devices-1workers",
+        "supportedUpToDevices": 10,
+        "rssSumMiB": 400
+      }
+    },
+    {
+      "id": "edge-ten-paraphrase",
+      "description": "Small box next to the rack, four cores and 8GB sata, running 10 MicroBT M56S miners.",
+      "expected": {
+        "status": "green",
+        "tier": "edge",
+        "workerCount": 1,
+        "matchingProfileId": "cap-10devices-1workers"
+      }
+    },
+    {
+      "id": "site-server-fifty-microbt",
+      "description": "About fifty MicroBT miners on a proper site server: 16 cores, 64 GiB, NVMe.",
+      "expected": {
+        "status": "green",
+        "tier": "site-server",
+        "workerCount": 2,
+        "matchingProfileId": "cap-50devices-2workers",
+        "supportedUpToDevices": 100,
+        "rssSumMiB": 800
+      }
+    },
+    {
+      "id": "site-server-eighty-interpolated",
+      "description": "80 Whatsminer M56S on a 16-core NVMe site-server with 64 GiB RAM.",
+      "expected": {
+        "status": "green",
+        "tier": "site-server",
+        "workerCount": 2,
+        "matchingProfileId": "cap-100devices-2workers",
+        "supportedUpToDevices": 100,
+        "rssSumMiB": 1040
+      }
+    },
+    {
+      "id": "mixed-sixty-forty",
+      "description": "Sixty Whatsminer M56S and forty Antminer S19 XP sharing one 16-core NVMe site server.",
+      "expected": {
+        "status": "green",
+        "tier": "site-server",
+        "workerCount": 2,
+        "matchingProfileId": "cap-100devices-2workers-mixed",
+        "supportedUpToDevices": 100,
+        "rssSumMiB": 1300
+      }
+    },
+    {
+      "id": "mixed-bench-fifteen",
+      "description": "A small mixed fleet like the example bench: ten Whatsminers and five Antminers, 8 cores, 32 GiB, SATA.",
+      "expected": {
+        "status": "green",
+        "tier": "site-server",
+        "workerCount": 2,
+        "matchingProfileId": "cap-15devices-2workers",
+        "rssSumMiB": 500
+      }
+    },
+    {
+      "id": "amber-two-hundred",
+      "description": "Two hundred Whatsminer M56S on a 16-core NVMe site-server, four worker processes.",
+      "expected": {
+        "status": "amber",
+        "tier": "site-server",
+        "workerCount": 4,
+        "matchingProfileId": "cap-200devices-4workers",
+        "supportedUpToDevices": 100
+      }
+    },
+    {
+      "id": "beyond-five-hundred",
+      "description": "Five hundred Whatsminer ASICs on one 16-core NVMe site-server.",
+      "expected": {
+        "status": "beyond-envelope",
+        "tier": "site-server",
+        "matchingProfileId": "cap-500devices-4workers",
+        "supportedUpToDevices": 100
+      }
+    },
+    {
+      "id": "unmeasured-avalon",
+      "description": "A handful of Avalon miners on an SD-card Raspberry Pi.",
+      "expected": {
+        "status": "unmeasured",
+        "tier": "edge"
+      }
+    }
+  ]
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-100devices-2workers-mixed.json

@@ -0,0 +1,24 @@
+{
+  "profileId": "cap-100devices-2workers-mixed",
+  "tier": "site-server",
+  "hardware": {
+    "referenceTier": "site-server",
+    "cpuCoresPhysical": 16,
+    "cpuCoresLogical": 32,
+    "ramGiB": 64,
+    "diskType": "nvme"
+  },
+  "deviceCount": 100,
+  "workerCount": 2,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 60 },
+    { "type": "mdk-worker-antminer", "model": "s19xp", "deviceCount": 40 }
+  ],
+  "status": "green",
+  "headroomRatio": 0.5,
+  "rssSumMiB": 1300,
+  "cpuSumPct": 65,
+  "readP99Ms": 75,
+  "actionP99Ms": 120,
+  "source": "fixture"
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-100devices-2workers.json

@@ -0,0 +1,23 @@
+{
+  "profileId": "cap-100devices-2workers",
+  "tier": "site-server",
+  "hardware": {
+    "referenceTier": "site-server",
+    "cpuCoresPhysical": 16,
+    "cpuCoresLogical": 32,
+    "ramGiB": 64,
+    "diskType": "nvme"
+  },
+  "deviceCount": 100,
+  "workerCount": 2,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 100 }
+  ],
+  "status": "green",
+  "headroomRatio": 0.55,
+  "rssSumMiB": 1200,
+  "cpuSumPct": 60,
+  "readP99Ms": 70,
+  "actionP99Ms": 110,
+  "source": "fixture"
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-10devices-1workers.json

@@ -0,0 +1,23 @@
+{
+  "profileId": "cap-10devices-1workers",
+  "tier": "edge",
+  "hardware": {
+    "referenceTier": "edge",
+    "cpuCoresPhysical": 4,
+    "cpuCoresLogical": 4,
+    "ramGiB": 8,
+    "diskType": "sata"
+  },
+  "deviceCount": 10,
+  "workerCount": 1,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 10 }
+  ],
+  "status": "green",
+  "headroomRatio": 0.15,
+  "rssSumMiB": 400,
+  "cpuSumPct": 20,
+  "readP99Ms": 40,
+  "actionP99Ms": 70,
+  "source": "fixture"
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-15devices-2workers.json

@@ -0,0 +1,24 @@
+{
+  "profileId": "cap-15devices-2workers",
+  "tier": "custom",
+  "hardware": {
+    "referenceTier": "custom",
+    "cpuCoresPhysical": 8,
+    "cpuCoresLogical": 16,
+    "ramGiB": 32,
+    "diskType": "sata"
+  },
+  "deviceCount": 15,
+  "workerCount": 2,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 10 },
+    { "type": "mdk-worker-antminer", "model": "s19xp", "deviceCount": 5 }
+  ],
+  "status": "green",
+  "headroomRatio": 0.2,
+  "rssSumMiB": 500,
+  "cpuSumPct": 25,
+  "readP99Ms": 50,
+  "actionP99Ms": 85,
+  "source": "fixture"
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-200devices-4workers.json

@@ -0,0 +1,23 @@
+{
+  "profileId": "cap-200devices-4workers",
+  "tier": "site-server",
+  "hardware": {
+    "referenceTier": "site-server",
+    "cpuCoresPhysical": 16,
+    "cpuCoresLogical": 32,
+    "ramGiB": 64,
+    "diskType": "nvme"
+  },
+  "deviceCount": 200,
+  "workerCount": 4,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 200 }
+  ],
+  "status": "amber",
+  "headroomRatio": 0.85,
+  "rssSumMiB": 2000,
+  "cpuSumPct": 90,
+  "readP99Ms": 140,
+  "actionP99Ms": 220,
+  "source": "fixture"
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-500devices-4workers.json

@@ -0,0 +1,23 @@
+{
+  "profileId": "cap-500devices-4workers",
+  "tier": "site-server",
+  "hardware": {
+    "referenceTier": "site-server",
+    "cpuCoresPhysical": 16,
+    "cpuCoresLogical": 32,
+    "ramGiB": 64,
+    "diskType": "nvme"
+  },
+  "deviceCount": 500,
+  "workerCount": 4,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 500 }
+  ],
+  "status": "red",
+  "headroomRatio": 1.4,
+  "rssSumMiB": 4500,
+  "cpuSumPct": 180,
+  "readP99Ms": 800,
+  "actionP99Ms": 2100,
+  "source": "fixture"
+}

package/dist/skills/mdk-site-sizing/eval/profiles/cap-50devices-2workers.json

@@ -0,0 +1,23 @@
+{
+  "profileId": "cap-50devices-2workers",
+  "tier": "site-server",
+  "hardware": {
+    "referenceTier": "site-server",
+    "cpuCoresPhysical": 16,
+    "cpuCoresLogical": 32,
+    "ramGiB": 64,
+    "diskType": "nvme"
+  },
+  "deviceCount": 50,
+  "workerCount": 2,
+  "workers": [
+    { "type": "mdk-worker-whatsminer", "model": "m56s", "deviceCount": 50 }
+  ],
+  "status": "green",
+  "headroomRatio": 0.35,
+  "rssSumMiB": 800,
+  "cpuSumPct": 40,
+  "readP99Ms": 55,
+  "actionP99Ms": 90,
+  "source": "fixture"
+}