@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-site-sizing/references/envelope.json

@@ -0,0 +1,284 @@
+{
+  "compiledAt": "1970-01-01T00:00:00.000Z",
+  "provenance": {
+    "kind": "fixture",
+    "note": "Fixture envelope for skill eval. Replace eval/profiles with committed harness reports (PE-1) and re-run compile-envelope.mjs."
+  },
+  "thresholds": {
+    "headroomGreenBelow": 0.7,
+    "headroomAmberBelow": 1,
+    "actionSubmitP99Ms": 2000,
+    "steadyCpuPctOfOneCore": 80
+  },
+  "profiles": [
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    }
+  ],
+  "supportedUpTo": {
+    "site-server": {
+      "mdk-worker-whatsminer": {
+        "devices": 100,
+        "workers": 2,
+        "profileId": "cap-100devices-2workers"
+      },
+      "mdk-worker-antminer,mdk-worker-whatsminer": {
+        "devices": 100,
+        "workers": 2,
+        "profileId": "cap-100devices-2workers-mixed"
+      }
+    },
+    "edge": {
+      "mdk-worker-whatsminer": {
+        "devices": 10,
+        "workers": 1,
+        "profileId": "cap-10devices-1workers"
+      }
+    },
+    "custom": {
+      "mdk-worker-antminer,mdk-worker-whatsminer": {
+        "devices": 15,
+        "workers": 2,
+        "profileId": "cap-15devices-2workers"
+      }
+    }
+  },
+  "formulas": {
+    "site-server|mdk-worker-whatsminer": {
+      "rssMiB": {
+        "base": 400,
+        "perDevice": 8
+      },
+      "cpuPct": {
+        "base": 23.333333333333336,
+        "perDevice": 0.3333333333333333
+      }
+    },
+    "site-server|mdk-worker-antminer,mdk-worker-whatsminer": {
+      "rssMiB": {
+        "base": 0,
+        "perDevice": 13
+      },
+      "cpuPct": {
+        "base": 0,
+        "perDevice": 0.65
+      }
+    },
+    "edge|mdk-worker-whatsminer": {
+      "rssMiB": {
+        "base": 0,
+        "perDevice": 40
+      },
+      "cpuPct": {
+        "base": 0,
+        "perDevice": 2
+      }
+    },
+    "custom|mdk-worker-antminer,mdk-worker-whatsminer": {
+      "rssMiB": {
+        "base": 0,
+        "perDevice": 33.333333333333336
+      },
+      "cpuPct": {
+        "base": 0,
+        "perDevice": 1.6666666666666667
+      }
+    }
+  }
+}

package/dist/skills/mdk-site-sizing/references/envelope.md

@@ -0,0 +1,42 @@
+# Measured envelope
+
+`envelope.json` is the only number source this skill may quote. It is compiled
+from capacity profiles (harness reports or the fixture set under `eval/profiles/`).
+
+## Profile shape
+
+Each profile is either a full harness report (`backend/tests/benchmark/results/<id>.json`)
+or the slim fields `compile-envelope.mjs` keeps:
+
+- `profileId`, `tier`, `hardware`
+- `deviceCount`, `workerCount`, `workers[]` (`type`, `model`, `deviceCount`)
+- `status` (`green` / `amber` / `red`)
+- `headroomRatio`, `rssSumMiB`, `cpuSumPct`, `readP99Ms`, `actionP99Ms`
+- `source` (`measured` or `fixture`)
+
+Pass/fail uses the same bars as the harness (`headroomGreenBelow` 0.7,
+`headroomAmberBelow` 1.0, action submit p99 2000 ms, steady CPU 80% of one
+core). **Supported up to** is the densest green profile on that family mix and
+tier, matching the [capacity metrics template](../../../../../../docs/guides/deployment/capacity-metrics-template.md).
+
+## Compile
+
+```bash
+# fixtures (default) — what the held-out bar runs against until PE-1
+node scripts/compile-envelope.mjs
+
+# a real results/ directory from npm run benchmark
+node scripts/compile-envelope.mjs --from <repo>/backend/tests/benchmark/results
+```
+
+`--from` must contain one `.json` per profile. Replacing fixtures with
+committed harness reports (the 1.0 PE-1 gate) is how this envelope becomes
+measured. After that, re-run `eval-held-out.mjs` and keep any case whose
+expected window still matches; drop or rewrite cases the new data invalidates.
+
+## Lookup
+
+`size-site.mjs` does not invent a topology. It picks the smallest covering
+profile (`deviceCount >= requested`) at the best status, interpolates RSS/CPU
+between the next-smaller green point and that cover, and refuses to label
+anything past the last non-red point as supported.

package/dist/skills/mdk-site-sizing/scripts/compile-envelope.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Compile measured (or fixture) capacity profiles into references/envelope.json.
+//
+//   node compile-envelope.mjs
+//   node compile-envelope.mjs --from ../../../../../backend/tests/benchmark/results
+//   node compile-envelope.mjs --from ./eval/profiles --out ../references/envelope.json
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { compileEnvelope } from './lib.mjs'
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+const SKILL_DIR = path.resolve(SCRIPT_DIR, '..')
+const DEFAULT_FROM = path.join(SKILL_DIR, 'eval', 'profiles')
+const DEFAULT_OUT = path.join(SKILL_DIR, 'references', 'envelope.json')
+
+const args = process.argv.slice(2)
+let fromDir = DEFAULT_FROM
+let outPath = DEFAULT_OUT
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--from') fromDir = path.resolve(args[++i])
+  else if (args[i] === '--out') outPath = path.resolve(args[++i])
+  else {
+    console.error(`unknown flag ${args[i]}`)
+    process.exit(2)
+  }
+}
+
+if (!fs.existsSync(fromDir)) {
+  console.error(`compile-envelope: source dir missing: ${fromDir}`)
+  process.exit(1)
+}
+
+const files = fs.readdirSync(fromDir).filter((n) => n.endsWith('.json')).sort()
+if (!files.length) {
+  console.error(`compile-envelope: no .json profiles in ${fromDir}`)
+  process.exit(1)
+}
+
+const raw = files.map((n) => JSON.parse(fs.readFileSync(path.join(fromDir, n), 'utf8')))
+const envelope = compileEnvelope(raw, { compiledAt: '1970-01-01T00:00:00.000Z' })
+fs.mkdirSync(path.dirname(outPath), { recursive: true })
+fs.writeFileSync(outPath, JSON.stringify(envelope, null, 2) + '\n')
+console.error(`compiled ${envelope.profiles.length} profile(s) -> ${outPath} (${envelope.provenance.kind})`)

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Held-out bar: parse each site description, size it, match the measured envelope.
+// Exit 0 only when every case matches. This is the skill's acceptance test.
+//
+//   node eval-held-out.mjs
+//   node eval-held-out.mjs --held-out ../eval/held-out.json --envelope ../references/envelope.json
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseSiteDescription, sizeSite, matchRecommendation } from './lib.mjs'
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+const SKILL_DIR = path.resolve(SCRIPT_DIR, '..')
+
+const args = process.argv.slice(2)
+let heldOutPath = path.join(SKILL_DIR, 'eval', 'held-out.json')
+let envelopePath = path.join(SKILL_DIR, 'references', 'envelope.json')
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--held-out') heldOutPath = path.resolve(args[++i])
+  else if (args[i] === '--envelope') envelopePath = path.resolve(args[++i])
+  else {
+    console.error(`unknown flag ${args[i]}`)
+    process.exit(2)
+  }
+}
+
+const heldOut = JSON.parse(fs.readFileSync(heldOutPath, 'utf8'))
+const envelope = JSON.parse(fs.readFileSync(envelopePath, 'utf8'))
+const cases = heldOut.cases || []
+
+let failed = 0
+for (const c of cases) {
+  const facts = parseSiteDescription(c.description)
+  const rec = sizeSite(facts, envelope)
+  const result = matchRecommendation(rec, c.expected)
+  if (result.ok) {
+    console.log(`PASS  ${c.id}`)
+  } else {
+    failed++
+    console.log(`FAIL  ${c.id}`)
+    for (const e of result.errors) console.log(`      ${e}`)
+    console.log(`      facts: ${JSON.stringify({ devices: facts.devices, deviceCount: facts.deviceCount, host: facts.host })}`)
+    console.log(`      rec:   ${JSON.stringify({ status: rec.status, tier: rec.tier, workerCount: rec.workerCount, matchingProfileId: rec.matchingProfileId, rssSumMiB: rec.rssSumMiB, supportedUpTo: rec.envelope?.supportedUpTo })}`)
+  }
+}
+
+const n = cases.length
+console.log(`${n - failed}/${n} held-out descriptions match the measured envelope`)
+process.exit(failed ? 1 : 0)