deadbyte-mcp 0.15.21 → 0.15.23

package/scripts/npm-release-r48.mjs

@@ -0,0 +1,252 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, readFile, rm, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+const node = process.execPath;
+const npmCli = process.env.npm_execpath || path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+
+function run(command, args, options = {}) {
+  const { cwd = root, timeout = 180000 } = options;
+  const r = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: false,
+    windowsHide: true,
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) {
+    const detail = (r.stderr || r.stdout || '').slice(-12000);
+    throw new Error(`${command} ${args.join(' ')} failed (exit=${r.status}, cwd=${cwd}):\n${detail}`);
+  }
+  return (r.stdout || '').trim();
+}
+
+function runNpm(args, options = {}) {
+  return run(node, [npmCli, ...args], options);
+}
+
+function runNpmInteractive(args, options = {}) {
+  const { cwd = root, timeout = 300000 } = options;
+  const r = spawnSync(node, [npmCli, ...args], {
+    cwd,
+    timeout,
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: false,
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw new Error('Interactive npm command failed (exit=' + r.status + ', cwd=' + cwd + ')');
+  return '';
+}
+
+function parseJson(text) {
+  const start = Math.min(...[text.indexOf('{'), text.indexOf('[')].filter(n => n >= 0));
+  if (!Number.isFinite(start)) throw new Error('Command JSON output missing:\n' + text.slice(0, 1000));
+  return JSON.parse(text.slice(start));
+}
+
+const allowedUnmanifested = new Set([
+  'MANIFEST.SHA256',
+  'controller/deadbyte-host-policy.json',
+  'controller/deadbyte-coding-policy.json',
+]);
+
+async function main() {
+  const isVerifyOnly = process.argv.includes('--verify-only') || process.argv.includes('--dry-run');
+
+  console.log(`[1/7] Reading package.json and checking registry publication status... ${isVerifyOnly ? '(MODE: VERIFY-ONLY / DRY-RUN)' : '(MODE: PUBLISH)'}`);
+  const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  const version = pkg.version;
+  if (pkg.name !== 'deadbyte-mcp') throw new Error(`unexpected package name: ${pkg.name}`);
+
+  const releaseBytes = await readFile(path.join(root, 'RELEASE.json'));
+  if (releaseBytes.subarray(0, 3).equals(Buffer.from([0xEF, 0xBB, 0xBF]))) {
+    throw new Error('RELEASE.json must be UTF-8 without BOM');
+  }
+  const release = JSON.parse(releaseBytes.toString('utf8'));
+  const provenance = JSON.parse(await readFile(path.join(root, 'PROVENANCE.json'), 'utf8'));
+  if (release.schema !== 'deadbyte.release.v1' || release.name !== pkg.name) {
+    throw new Error('RELEASE.json schema/package identity mismatch');
+  }
+  if (release.version !== version) {
+    throw new Error(`RELEASE.json version mismatch: package=${version} release=${release.version}`);
+  }
+  if (provenance.version !== version) {
+    throw new Error(`PROVENANCE.json version mismatch: package=${version} provenance=${provenance.version}`);
+  }
+  if (release.parent?.release_id !== provenance.parent_release_id ||
+      release.parent?.manifest_sha256 !== provenance.parent_manifest_sha256 ||
+      release.parent?.generation_manifest_sha256 !== provenance.parent_generation_manifest_sha256) {
+    throw new Error('RELEASE.json parent identity does not match sealed PROVENANCE.json lineage');
+  }
+
+  const existing = spawnSync(node, [npmCli, 'view', `deadbyte-mcp@${version}`, 'version', '--json'], {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: false, windowsHide: true,
+  });
+  const existingText = (existing.stdout || '').trim();
+  const isAlreadyPublished = existing.status === 0 && existingText && existingText !== 'null';
+
+  if (isAlreadyPublished) {
+    if (!isVerifyOnly) {
+      throw new Error(`deadbyte-mcp@${version} is already published on registry: ${existingText}`);
+    } else {
+      console.log(`Notice: deadbyte-mcp@${version} is already published on registry (${existingText}), proceeding with pre-publish verification only.`);
+    }
+  }
+
+  console.log('[2/7] Pre-pack gates: verifying working tree manifest and doctor...');
+  run(node, [path.join(root, 'scripts', 'release-manifest.mjs'), 'verify']);
+  run(node, [path.join(root, 'src', 'deadbyte-cli.mjs'), 'doctor']);
+
+  console.log('[3/7] Packing artifact with npm pack...');
+  const packed = parseJson(runNpm(['pack', '--json'], { timeout: 180000 }));
+  const filename = packed?.[0]?.filename;
+  if (!filename) throw new Error('npm pack did not return a tarball filename');
+  const tarball = path.join(root, filename);
+  let releaseSucceeded = false;
+  let publishAttempted = false;
+
+  try {
+    console.log('[4/7] Verifying packed artifact file surface against MANIFEST.SHA256 and packaging contract...');
+    const manifestText = await readFile(path.join(root, 'MANIFEST.SHA256'), 'utf8');
+    const manifestEntries = new Set();
+    for (const line of manifestText.split(/\r?\n/)) {
+      if (!line) continue;
+      const m = /^([0-9a-f]{64})\s+(.+)$/.exec(line);
+      if (m) manifestEntries.add(m[2]);
+    }
+
+    const tarListing = run('tar', ['-tf', tarball], { timeout: 60000 });
+    const tarFiles = new Set(
+      tarListing
+        .split(/\r?\n/)
+        .map(s => s.trim().replaceAll('\\', '/'))
+        .filter(s => s.startsWith('package/') && s.length > 'package/'.length && !s.endsWith('/'))
+        .map(s => s.slice('package/'.length))
+    );
+
+    const missingInTarball = [];
+    for (const rel of manifestEntries) {
+      if (!tarFiles.has(rel)) missingInTarball.push(rel);
+    }
+    if (missingInTarball.length > 0) {
+      throw new Error(`Tarball missing files declared in manifest (${missingInTarball.length}): ${missingInTarball.slice(0, 10).join(', ')}`);
+    }
+
+    const unexpectedInTarball = [];
+    for (const rel of tarFiles) {
+      if (!manifestEntries.has(rel) && !allowedUnmanifested.has(rel)) {
+        unexpectedInTarball.push(rel);
+      }
+    }
+    if (unexpectedInTarball.length > 0) {
+      throw new Error(`Tarball contains unexpected files not in manifest or allowlist (${unexpectedInTarball.length}): ${unexpectedInTarball.slice(0, 10).join(', ')}`);
+    }
+
+    console.log(`Packed artifact surface verified OK: ${tarFiles.size} package files, all ${manifestEntries.size} manifest entries present.`);
+
+    console.log('[5/7] Pre-publish artifact isolation gate in sandbox...');
+    const sandbox = await mkdtemp(path.join(os.tmpdir(), 'deadbyte-release-verify-'));
+    try {
+      run('tar', ['-xzf', tarball, '-C', sandbox]);
+      const extractedPackage = path.join(sandbox, 'package');
+
+      const extractedVersion = run(node, [path.join(extractedPackage, 'src', 'deadbyte-cli.mjs'), '--version'], {
+        cwd: extractedPackage,
+      });
+      if (extractedVersion !== version) {
+        throw new Error(`Isolated package version mismatch: expected=${version} got=${extractedVersion}`);
+      }
+
+      run(node, [path.join(extractedPackage, 'src', 'deadbyte-cli.mjs'), 'doctor'], {
+        cwd: extractedPackage,
+      });
+
+      console.log('Artifact isolation gate PASS (clean doctor and version check on unpacked tarball in sandbox)');
+    } finally {
+      await rm(sandbox, { recursive: true, force: true }).catch(() => {});
+    }
+
+    if (isVerifyOnly) {
+      console.log('[6/7] [VERIFY-ONLY] Skipping npm publish.');
+      console.log('[7/7] [VERIFY-ONLY] Skipping external registry smoke test.');
+      console.log('\nVERIFY-ONLY PIPELINE PASS: All pre-pack, artifact surface, and isolated sandbox gates passed successfully.');
+      return;
+    }
+
+    console.log('[6/7] Publishing artifact to npm registry...');
+    publishAttempted = true;
+    let publishOut;
+    try {
+      publishOut = runNpmInteractive(['publish', tarball, '--access', 'public', '--auth-type=web'], { timeout: 300000 });
+    } catch (publishError) {
+      const detail = String(publishError?.message || publishError);
+      if (/EOTP|one-time password|two-factor|2FA|security.?key|authentication/i.test(detail)) {
+        console.error('Publish requires interactive npm authentication (Security Key/WebAuthn).');
+        console.error('Tarball preserved for retry: ' + tarball);
+      }
+      throw publishError;
+    }
+    const published = parseJson(runNpm(['view', `deadbyte-mcp@${version}`, 'version', 'dist.integrity', 'dist.tarball', '--json'], { timeout: 120000 }));
+    const tags = parseJson(runNpm(['view', 'deadbyte-mcp', 'dist-tags', '--json'], { timeout: 120000 }));
+
+    console.log('[7/7] Post-publish external registry smoke test (executed outside repo in temp)...');
+    const tempDir = os.tmpdir();
+    const externalVersion = runNpm(['exec', '--yes', `--package=deadbyte-mcp@${version}`, '--', 'deadbyte-mcp', '--version'], {
+      cwd: tempDir,
+      timeout: 300000,
+    });
+    if (externalVersion !== version) {
+      throw new Error(`External registry smoke test version mismatch: expected=${version} got=${externalVersion}`);
+    }
+
+    const externalDoctor = runNpm(['exec', '--yes', `--package=deadbyte-mcp@${version}`, '--', 'deadbyte-mcp', 'doctor'], {
+      cwd: tempDir,
+      timeout: 300000,
+    });
+
+    console.log('[8/8] Activating the published release into the live immutable slot and waiting for verified handoff...');
+    run(node, [path.join(root, 'scripts', 'deploy-r48.mjs')], { cwd: root, timeout: 900000 });
+
+    releaseSucceeded = true;
+    console.log('\nRELEASE SUCCESSFUL:');
+    console.log(JSON.stringify({
+      status: 'published',
+      name: pkg.name,
+      version,
+      tarball: filename,
+      published,
+      published_output_tail: publishOut.slice(-2000),
+      dist_tags: tags,
+      external_smoke: {
+        version_output: externalVersion,
+        doctor_status: 'ok',
+      },
+    }, null, 2));
+
+  } finally {
+    if (releaseSucceeded || !publishAttempted) {
+      await unlink(tarball).catch(() => {});
+    } else {
+      console.error('Release artifact preserved after failure: ' + tarball);
+    }
+  }
+}
+
+main().catch(err => {
+  console.error('\nRELEASE ABORTED / FAILED:');
+  console.error(err?.stack || err);
+  process.exitCode = 1;
+});
+
+
+
+
+
+
+

package/scripts/pcb-skill-src-SKILL.md.txt

@@ -0,0 +1,67 @@
+---
+name: deadbyte-advanced-pcb-engineering
+description: Evidence-driven advanced PCB engineering workflow for schematic review, constraint capture, stackup-aware placement and routing, power and signal integrity, EMC, DFM/DFT, KiCad verification, manufacturing release, and hardware bring-up.
+version: 1.0.0
+audience: agent
+---
+
+# DEADBYTE ADVANCED PCB ENGINEERING
+
+Use this skill for serious PCB design, review, rework, manufacturing preparation, and board bring-up. It is optimized for KiCad source artifacts but the engineering workflow applies to other EDA tools when equivalent primary evidence is available.
+
+## Core law
+
+The schematic expresses intent. The board file expresses implementation. ERC, DRC, manufacturing outputs, measurements, and hardware observations are evidence.
+
+Never invent a stackup, dielectric constant, loss tangent, copper thickness, trace impedance, current capacity, thermal rise, manufacturer capability, timing budget, or connector pinout. Mark missing inputs as UNKNOWN and stop the affected calculation or claim.
+
+Do not call a board ready because it renders, routes, exports Gerbers, or passes one checker.
+
+## Operating loop
+
+1. Freeze board identity: project, revision, source hashes, EDA version, target manufacturer, board class, environment, and physical envelope.
+2. Extract the electrical interface matrix from the schematic: rails, clocks, resets, boot straps, buses, differential pairs, analog nodes, RF, connectors, test points, and programming paths.
+3. Write the constraint contract before routing. Separate electrical, stackup, fabrication, assembly, mechanical, thermal, and test constraints.
+4. Establish stackup and reference-plane assumptions before impedance or high-speed routing.
+5. Place from physics outward: connectors and mechanical locks, power entry, clocks, high-speed endpoints, regulators, memory, analog, then low-speed logic.
+6. Establish return-current paths before route aesthetics. Do not cross plane splits with fast signals unless the return path is explicitly engineered.
+7. Close power integrity: source path, protection, regulation, bulk storage, local decoupling, high-frequency loop area, transient current, copper loss, and thermal dissipation.
+8. Route critical interfaces from their actual edge rate and topology. Length matching is subordinate to topology, reference continuity, coupling, and timing budget.
+9. Close EMC and ESD paths at the boundary. Keep noisy current loops local. Give external transients a short controlled path away from sensitive logic.
+10. Add DFM and DFT evidence: clearances, annular rings, drill limits, solder-mask policy, fiducials, tooling, test points, programming access, polarity/orientation checks, and rework access.
+11. Run deterministic board probe, EDA ERC/DRC, and the declared constraint gate. Preserve exact outputs and hashes.
+12. Export fabrication and assembly artifacts only after source verification. Hash the release set and record the exact source revision that produced it.
+13. Build a bring-up plan before power is applied. Start with shorts and rail resistance, current-limited power, sequencing, clocks, resets, boot straps, debug access, then peripherals.
+14. Close each claim with observed evidence. Report PASS, FAIL, PARTIALLY VERIFIED, BLOCKED BY EVIDENCE, or HYPOTHESIS ONLY.
+
+## Evidence hierarchy
+
+Prefer datasheets and package drawings for external facts; native schematic and PCB sources for implemented connectivity and geometry; EDA ERC/DRC for rule checking; deterministic source inspection for structural observations; manufacturing outputs for release consistency; bench measurements for physical behavior.
+
+A screenshot is weak evidence. A rendered trace is not a measured impedance. A DRC pass is not signal-integrity proof.
+
+## High-speed rule
+
+Before tuning a fast net, identify driver, receiver, signaling standard, edge rate, topology, reference plane, layer transition, via structure, stackup geometry, termination, timing budget, and allowed discontinuities. If any parameter required for a numerical claim is missing, do not fabricate the number.
+
+## Bundled references
+
+Load only what the task needs:
+- references/constraint-model.md
+- references/high-speed-layout.md
+- references/power-integrity.md
+- references/emc-mechanical-dfm.md
+- references/bringup-evidence.md
+- references/kicad-native.md
+
+## Deterministic helpers
+
+Use scripts/kicad_pcb_probe.py on a native KiCad PCB file. It performs a non-executing S-expression parse and emits source hash, format identity, layer list, net names, footprint/segment/via/zone counts, track-width range, and via geometry range.
+
+Use scripts/pcb_constraint_gate.py with a JSON contract to compare observed source metrics against explicit minima and required names. The gate can prove only the rules it implements. It does not replace ERC, DRC, field solvers, thermal analysis, or bench measurement.
+
+## Completion contract
+
+Before claiming FAB READY or BOARD VERIFIED, record exact source hashes, exact EDA/tool versions, ERC and DRC results, constraint-gate result, unresolved waivers, fabrication and assembly output hashes, unverified SI/PI/thermal/EMC/mechanical assumptions, and physical bring-up evidence for hardware-dependent claims.
+
+Never weaken a rule or verifier to make the board pass.

package/scripts/pcb-skill-src-bringup-evidence.md.txt

@@ -0,0 +1,22 @@
+# Release and Hardware Bring-Up Evidence
+
+A pre-fabrication release should bind source PCB/schematic hashes, project revision, BOM, fabrication outputs, drill outputs, pick-and-place, assembly drawings, fabrication notes/stackup, mechanical exchange artifacts where used, ERC/DRC logs, explicit waivers, and tool versions.
+
+Regenerate the bundle from the exact released source revision. Do not mix old exports.
+
+Bring-up order:
+1. Inspect polarity, orientation, bridges, missing parts, and damaged connectors.
+2. Measure resistance from major rails to ground and investigate suspicious lows.
+3. Use a current-limited supply for first power where the design permits.
+4. Verify input protection and primary rails.
+5. Verify sequencing and enables.
+6. Verify reset.
+7. Verify oscillators/clocks with a probing method that does not invalidate the measurement.
+8. Verify boot straps and debug/programming access.
+9. Program the smallest known-good image.
+10. Bring up one peripheral class at a time.
+11. Record current consumption, temperatures, rails, and anomalies.
+
+Physical PASS requires observed hardware evidence. DRC and source review reduce risk but do not substitute for power-on behavior.
+
+When a board fails, freeze the failing revision and evidence before rework. Record bodges and substitutions.

package/scripts/pcb-skill-src-constraint-model.md.txt

@@ -0,0 +1,17 @@
+# PCB Constraint Model
+
+Treat constraints as source data, not prose hidden in chat history.
+
+Record board identity: revision, EDA format/version, intended fab, assembly process, environmental range, input power, mechanical envelope, layer count target, controlled-impedance requirement, and safety/isolation class if any.
+
+For every critical interface record endpoints and pins, signaling standard, voltage, direction, topology, data rate, edge rate, impedance target only when stackup data exists, reference plane, allowed layers, via structure, termination, timing/skew budget, spacing/isolation, boundary protection, and probe requirement.
+
+For every rail record nominal voltage and tolerance, source/regulator, steady and transient current estimates, sequencing, bulk and local decoupling, sensitive loads, copper path, connector limits, dissipation, and measurement points.
+
+Separate datasheet rules, fabrication rules, design rules, and evidence rules. Conflicts are not averaged. Resolve which rule governs.
+
+Do not infer controlled impedance from trace width alone. Width without dielectric geometry and material parameters is insufficient.
+
+Do not use generic current charts as a blind oracle. Temperature rise depends on geometry, copper thickness, plane coupling, airflow, ambient, nearby heat, and reliability margin.
+
+A numeric rule without provenance is a hypothesis, not a constraint.

package/scripts/pcb-skill-src-emc-mechanical-dfm.md.txt

@@ -0,0 +1,17 @@
+# EMC, Mechanical, DFM, and DFT
+
+Treat every external cable, connector, shield, and exposed conductor as an EMC/ESD boundary.
+
+Place transient protection where energy enters. Give surge and ESD current a short low-inductance path to its intended return. Do not route discharge through sensitive logic by accident.
+
+Keep common-mode conversion low by preserving pair symmetry and reference continuity.
+
+Name the current path instead of arguing from labels such as analog ground or digital ground. A split plane is justified only when the complete signal and return topology supports it.
+
+Mechanical review must verify connector mating direction and insertion envelope, mounting-hole keepouts, screw-head clearance, component height, board-edge clearance, heatsink/airflow space, cable bend/strain relief, and test/programming access after assembly.
+
+Bind fabrication rules to the chosen fab: trace/space, copper, drill, annular ring, aspect ratio, solder mask, copper-to-edge, impedance service, controlled-depth operations, finish, material, and panel constraints. Do not silently rely on generic KiCad defaults.
+
+Assembly review must cover package orientation, pin-1 evidence, polarized parts, courtyard conflicts, solderability, paste exceptions, fiducials, side restrictions, and rework access.
+
+Expose test points for critical rails, reset, clock, boot straps, programming/debug, and important buses where practical.

package/scripts/pcb-skill-src-high-speed-layout.md.txt

@@ -0,0 +1,27 @@
+# High-Speed Layout
+
+High speed is set by transition time and interconnect electrical length, not just protocol bit rate.
+
+Route decision order:
+1. Topology.
+2. Reference continuity.
+3. Placement and pin escape.
+4. Discontinuities and layer changes.
+5. Coupling and spacing.
+6. Termination.
+7. Timing and skew.
+8. Cosmetic length matching.
+
+A perfectly length-matched pair over a broken return path is still wrong.
+
+Identify the reference plane for every fast route segment. When changing reference planes, provide a nearby return transition appropriate to the stackup and signal energy. Do not route fast nets over plane voids, connector keepouts, split references, or deep antipads without explicit analysis.
+
+For differential pairs, preserve the same reference environment and avoid gratuitous uncoupling. Include package, connector, via, and pin-escape skew in the budget. Visual spacing does not prove differential impedance.
+
+Count every via transition. At high edge rates, barrel, unused stub, antipad, return transition, and connector launch can dominate a short trace.
+
+For memory, use the controller and memory-vendor topology. Address/command, clock, data, strobe, and mask groups have different timing relationships. Do not force one global length target.
+
+For USB and Ethernet, follow the transceiver/connector reference design for termination, magnetics, and protection placement. Keep pair symmetry and return continuity.
+
+Source geometry can prove routing choices. It cannot alone prove insertion loss, eye margin, impedance, or emissions.

package/scripts/pcb-skill-src-kicad-native.md.txt

@@ -0,0 +1,30 @@
+# KiCad Native Evidence
+
+Prefer native .kicad_sch and .kicad_pcb sources over screenshots.
+
+Run:
+python scripts/kicad_pcb_probe.py path/to/board.kicad_pcb > board-probe.json
+
+The probe does not execute the board. It reports SHA-256, file size, KiCad format identity, layers, net names, footprint/segment/via/zone counts, segment-width range, and via geometry range.
+
+Example constraint contract:
+{
+  "required_layers": ["F.Cu", "B.Cu"],
+  "min_copper_layers": 2,
+  "min_track_width_mm": 0.15,
+  "min_via_diameter_mm": 0.45,
+  "min_via_drill_mm": 0.20,
+  "required_nets": ["GND"],
+  "min_footprints": 1
+}
+
+Run:
+python scripts/pcb_constraint_gate.py board-probe.json board-contract.json
+
+The gate fails only on implemented explicit rules. It cannot infer missing engineering constraints.
+
+When kicad-cli is installed, record its exact version first and use the commands supported by that installed release for ERC, DRC, and exports. Preserve exit status and output. Do not guess command switches across versions.
+
+Probe PASS plus constraint-gate PASS is not equivalent to KiCad DRC PASS. Keep evidence classes separate.
+
+Visual inspection is useful for placement, return-path discontinuities, reference transitions, neck-downs, thermal paths, connector mechanics, and markings, but it cannot override parser or DRC evidence.

package/scripts/pcb-skill-src-kicad_pcb_probe.py.txt

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+import argparse, hashlib, json, math, sys
+
+def tokenize(text):
+    i, n = 0, len(text)
+    while i < n:
+        c = text[i]
+        if c.isspace():
+            i += 1
+            continue
+        if c in "()":
+            yield c
+            i += 1
+            continue
+        if c == '"':
+            i += 1
+            out = []
+            while i < n:
+                c = text[i]
+                if c == '"':
+                    i += 1
+                    break
+                if c == "\\" and i + 1 < n:
+                    out.append(text[i + 1])
+                    i += 2
+                else:
+                    out.append(c)
+                    i += 1
+            else:
+                raise ValueError("unterminated string")
+            yield ("ATOM", "".join(out))
+            continue
+        j = i
+        while j < n and (not text[j].isspace()) and text[j] not in "()":
+            j += 1
+        yield ("ATOM", text[i:j])
+        i = j
+
+def parse(text):
+    stack, root = [], None
+    for tok in tokenize(text):
+        if tok == "(":
+            node = []
+            if stack:
+                stack[-1].append(node)
+            stack.append(node)
+        elif tok == ")":
+            if not stack:
+                raise ValueError("unexpected close")
+            node = stack.pop()
+            if not stack:
+                if root is not None:
+                    raise ValueError("multiple top-level forms")
+                root = node
+        else:
+            if not stack:
+                raise ValueError("atom outside list")
+            stack[-1].append(tok[1])
+    if stack:
+        raise ValueError("unclosed list")
+    if root is None:
+        raise ValueError("empty file")
+    return root
+
+def head(node):
+    return node[0] if isinstance(node, list) and node and isinstance(node[0], str) else None
+
+def child(node, name):
+    if not isinstance(node, list):
+        return None
+    for x in node[1:]:
+        if isinstance(x, list) and head(x) == name:
+            return x
+    return None
+
+def scalar(node, name):
+    x = child(node, name)
+    return x[1] if x is not None and len(x) > 1 and isinstance(x[1], str) else None
+
+def number(v):
+    try:
+        x = float(v)
+        return x if math.isfinite(x) else None
+    except Exception:
+        return None
+
+def metric(values):
+    xs = sorted(x for x in values if x is not None)
+    if not xs:
+        return {"count": 0, "min": None, "max": None, "unique": []}
+    uniq = []
+    for x in xs:
+        if not uniq or abs(x - uniq[-1]) > 1e-12:
+            uniq.append(x)
+    return {"count": len(xs), "min": xs[0], "max": xs[-1], "unique": uniq[:128]}
+
+def main():
+    ap = argparse.ArgumentParser(description="Deterministic structural probe for KiCad PCB files")
+    ap.add_argument("board")
+    ap.add_argument("--pretty", action="store_true")
+    ns = ap.parse_args()
+    data = open(ns.board, "rb").read()
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise SystemExit("UTF-8 decode failed: %s" % e)
+    root = parse(text)
+    if head(root) != "kicad_pcb":
+        raise SystemExit("not a kicad_pcb root")
+
+    layers_node = child(root, "layers")
+    layers = []
+    if layers_node:
+        for x in layers_node[1:]:
+            if isinstance(x, list) and len(x) >= 3:
+                layers.append({"id": x[0], "name": x[1], "type": x[2]})
+    copper_layers = [x["name"] for x in layers if isinstance(x.get("name"), str) and x["name"].endswith(".Cu")]
+
+    nets, widths, via_sizes, via_drills = [], [], [], []
+    footprints = segments = vias = zones = 0
+
+    for x in root[1:]:
+        h = head(x)
+        if h == "net" and len(x) >= 3:
+            nets.append(str(x[2]))
+        elif h in ("footprint", "module"):
+            footprints += 1
+        elif h == "segment":
+            segments += 1
+            widths.append(number(scalar(x, "width")))
+        elif h == "via":
+            vias += 1
+            via_sizes.append(number(scalar(x, "size")))
+            d = child(x, "drill")
+            if d is not None and len(d) > 1:
+                via_drills.append(number(d[1]))
+        elif h == "zone":
+            zones += 1
+
+    result = {
+        "schema": "deadbyte.kicad-pcb-probe.v1",
+        "path": ns.board,
+        "sha256": hashlib.sha256(data).hexdigest(),
+        "bytes": len(data),
+        "kicad": {"version": scalar(root, "version"), "generator": scalar(root, "generator")},
+        "layers": layers,
+        "copper_layers": copper_layers,
+        "copper_layer_count": len(copper_layers),
+        "nets": sorted(set(nets)),
+        "counts": {"footprints": footprints, "segments": segments, "vias": vias, "zones": zones},
+        "track_width_mm": metric(widths),
+        "via_diameter_mm": metric(via_sizes),
+        "via_drill_mm": metric(via_drills)
+    }
+    json.dump(result, sys.stdout, indent=2 if ns.pretty else None, sort_keys=True)
+    sys.stdout.write("\n")
+
+if __name__ == "__main__":
+    main()