mdk-site-sizing

Files (16)

• SKILL.md
• held-out.json · eval/
• cap-100devices-2workers-mixed.json · eval/profiles/
• cap-100devices-2workers.json · eval/profiles/
• cap-10devices-1workers.json · eval/profiles/
• cap-15devices-2workers.json · eval/profiles/
• cap-200devices-4workers.json · eval/profiles/
• cap-500devices-4workers.json · eval/profiles/
• cap-50devices-2workers.json · eval/profiles/
• envelope.json · references/
• envelope.md · references/
• compile-envelope.mjs · scripts/
• eval-held-out.mjs · scripts/
• lib.mjs · scripts/
• parse-site.mjs · scripts/
• size-site.mjs · scripts/

SKILL.md (first lines)

# 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).

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk