chore: sanity-check sweep — registry stub, CI badges, benchmarks (#5)

Six items, one PR:

1. Python source: ruff, mypy --strict, pytest 15/15 — clean. No
   formatting changes needed.
2. Registry packages: replace `npm install`/`pip install` blocks with
   from-source instructions. PyPI and npm are 404 for vella-sdk; the
   one-liners were inviting users into a dead end. Note v1.0.1 will
   land registry packages.
3. Clean-clone validation: documented Python venv pin to 3.10+ in the
   install instructions to surface the requires-python floor (system
   python3 is 3.9 on many macOS installs and silently picks the wrong
   interpreter).
4. CI badges: add Test SDK / Verify Test Vectors / Lint Schemas badges
   under the DOI badge.
5. Benchmarks: new benchmarks/ harness for both SDKs.
   - 11 independent runs, warmup phase, median-of-medians headline
   - GC quiesced (Node --expose-gc, Python gc.disable in inner loop)
   - Ephemeral ECDSA P-256 key for with-proof scenario
   - 100K samples decision-only / 10K with-proof per run
   - Reference results checked in for Apple M2 Pro (Node 22 / Py 3.12)
   - Linux x86_64 row left open for community contribution
6. Move premature commercial-component paragraph: drop the line-26
   "separate commercial components" sentence so it doesn't precede
   Install/Quickstart. The dedicated "Where this SDK fits" section
   later in the README remains the single place commercial scope is
   discussed.

Co-authored-by: Mike Wilson <mwlog1c1-netizen@users.noreply.github.com>

Author: mwlog1c

README.md

@@ -1,4 +1,7 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19738377.svg)](https://doi.org/10.5281/zenodo.19738377)
+[![Test SDK](https://github.com/vellacognitive/vella-substrate/actions/workflows/test-sdk.yml/badge.svg)](https://github.com/vellacognitive/vella-substrate/actions/workflows/test-sdk.yml)
+[![Verify Test Vectors](https://github.com/vellacognitive/vella-substrate/actions/workflows/verify-test-vectors.yml/badge.svg)](https://github.com/vellacognitive/vella-substrate/actions/workflows/verify-test-vectors.yml)
+[![Lint Schemas](https://github.com/vellacognitive/vella-substrate/actions/workflows/lint-schemas.yml/badge.svg)](https://github.com/vellacognitive/vella-substrate/actions/workflows/lint-schemas.yml)
 
 # VELLA — Governance Substrate for AI Agents & Autonomous Systems
 
@@ -23,8 +26,6 @@ VELLA decides whether an action is authorized before it runs. The calling system
 
 The SDK is designed for in-process, low-latency adjudication; the authority decision can sit directly on the action path rather than being deferred to post-hoc logging.
 
-This public SDK is a focused reference implementation of the VELLA decision/proof primitive. Production deployment patterns that require a runtime service, sidecar adapter, Helm packaging, or management plane are supported through separate commercial components.
-
 **Start here:**
 - [An Inspectable Substrate for AI Governance](https://vellacognitive.com/research/an-inspectable-substrate-for-ai-governance) — the conceptual argument (~14 min read)
 - [Quickstart](#quick-example) — Node or Python SDK, working example in 2 minutes
@@ -33,29 +34,31 @@ This public SDK is a focused reference implementation of the VELLA decision/proo
 
 ## Install
 
-```bash
-npm install @vellacognitive/vella-sdk
-```
-
-```bash
-pip install vella-sdk
-```
-
-## Local development
+> **Registry packages are not yet published.** `npm install @vellacognitive/vella-sdk` and `pip install vella-sdk` will be live with v1.0.1. Until then, install from source against this repository — the SDK has no external runtime dependencies on Node and one (`cryptography`) on Python.
 
 ### Node SDK from source
 
 ```bash
-cd sdk/node
+git clone https://github.com/vellacognitive/vella-substrate.git
+cd vella-substrate/sdk/node
 npm ci
 npm test
 ```
 
+Then import directly from the checkout, or `npm pack` to produce a tarball:
+
+```bash
+npm pack          # produces vellacognitive-vella-sdk-1.0.0.tgz
+# in your project:
+npm install /path/to/vellacognitive-vella-sdk-1.0.0.tgz
+```
+
 ### Python SDK from source
 
 ```bash
-cd sdk/python
-python3 -m venv .venv
+git clone https://github.com/vellacognitive/vella-substrate.git
+cd vella-substrate/sdk/python
+python3.10 -m venv .venv      # 3.10+ required; replace with python3.11/3.12 as available
 . .venv/bin/activate
 python -m pip install --upgrade pip
 pip install -e ".[dev]"
@@ -107,6 +110,8 @@ print(result["proof_bundle"]["envelope_id"])
   - `verify/verify.js`, `verify/verify.py`, `verify/verify.sh` standalone proof-bundle verifiers
 - Test vectors:
   - `test-vectors/valid/` and `test-vectors/tampered/` for verifier CI and audit workflows
+- Benchmarks:
+  - `benchmarks/` reproducible latency harness for both SDKs — see [`benchmarks/README.md`](benchmarks/README.md) for methodology and reference results
 
 ## Where this SDK fits
 

benchmarks/README.md

@@ -0,0 +1,107 @@
+# VELLA SDK — Latency Benchmarks
+
+Reproducible benchmarks for the in-process SDK. Backs the latency claims in
+[`DEPLOYMENT.md`](../DEPLOYMENT.md).
+
+The harness measures two scenarios:
+
+- **decision-only** — `govern({intent, evidenceMask})`. Hot path, no proof bundle.
+- **with-proof** — `govern({intent, evidenceMask, proof: {signingKey}})`. Includes
+  envelope construction, SHA-256 hashing, and ECDSA P-256 signing.
+
+## Methodology
+
+- **Warmup.** Each scenario runs a warmup phase (10K iterations decision-only,
+  2K with-proof) before any measurement, so JIT and import caches are stable.
+- **Independent runs.** Each scenario then runs 11 independent measurement
+  passes. Per-pass percentiles are computed from the full sample distribution;
+  the headline metric is the **median of the per-run medians** (resilient to a
+  single noisy run).
+- **GC quiesced.** Node runs with `--expose-gc` and calls `global.gc()`
+  between runs. Python calls `gc.collect()` then `gc.disable()` for the timed
+  inner loop, re-enabled afterward.
+- **Ephemeral signing key.** A fresh ECDSA P-256 key is generated at startup
+  for the with-proof scenario — no fixture coupling.
+- **Timer.** `process.hrtime.bigint()` (Node) and `time.perf_counter_ns()`
+  (Python). Monotonic, nanosecond resolution. Timer overhead (~50 ns/sample)
+  applies equally to all scenarios.
+- **Sample sizes.** Decision-only: 100K iterations × 11 runs = 1.1M samples
+  per runtime. With-proof: 10K × 11 = 110K samples per runtime.
+
+The harness emits both the median-of-medians and the full quantile breakdown
+of run #1 (so you can see what tail latency on a representative pass looks
+like, not just a smoothed central tendency).
+
+## Running
+
+```bash
+# full run, both runtimes, human-readable
+./benchmarks/run.sh
+
+# JSON output for archival or comparison
+./benchmarks/run.sh --json > benchmarks/results/my-machine.json
+
+# ~10s sanity check at reduced N
+./benchmarks/run.sh --quick
+```
+
+Or per-runtime:
+
+```bash
+node --expose-gc benchmarks/bench.js
+python3 benchmarks/bench.py
+```
+
+The Python script adds `sdk/python` to `sys.path` directly, so `pip install`
+is not required — only `cryptography` needs to be available in the active
+environment.
+
+## Reference results
+
+### Apple M2 Pro · macOS 26.4 · Node 22.21 / Python 3.12.13
+
+Source JSON: [`results/macos-arm64-m2pro.json`](results/macos-arm64-m2pro.json)
+
+| Runtime          | Scenario      | p50    | p95    | p99    |
+| ---------------- | ------------- | ------ | ------ | ------ |
+| Node 22 / M2 Pro | decision-only | 0.13µs | 0.13µs | 0.17µs |
+| Node 22 / M2 Pro | with-proof    | 153µs  | 179µs  | 247µs  |
+| Python 3.12 / M2 Pro | decision-only | 0.96µs | 1.04µs | 1.17µs |
+| Python 3.12 / M2 Pro | with-proof    | 158µs  | 180µs  | 227µs  |
+
+(All values are median-of-medians across 11 runs.)
+
+### Linux x86_64 · *(pending — submit a PR with your `results/<machine>.json`)*
+
+The harness is intentionally architecture-agnostic. Run it on your hardware
+and either commit the JSON to `benchmarks/results/` or paste the table into
+an issue. We will keep the reference table here in sync as more numbers come
+in.
+
+## Notes on interpretation
+
+- **Decision-only is dominated by function-call overhead** at this scale.
+  The actual policy evaluation is a small constant-time check; the measurement
+  largely reflects the runtime's own dispatch cost. Node's V8 inlines the hot
+  path aggressively, hence the ~130 ns floor.
+- **With-proof is dominated by ECDSA signing** (~150 µs is roughly what a
+  P-256 sign costs on Apple Silicon). Hashing and envelope serialization are
+  comparable noise.
+- **The wide p99→max gap on a single run** (visible in the JSON's
+  `sample_run_ns` field) is the OS scheduler, not the SDK. The
+  median-of-medians strips most of it; if your SLO is tail-bound, plan for
+  ~500 µs decision-only worst case on a typical desktop and budget the
+  difference against your scheduler's QoS guarantees.
+
+## Reproducibility
+
+The harness is deterministic given an unloaded machine. To compare numbers
+between runs:
+
+1. Quiesce background processes (close browsers, dev servers, etc.).
+2. Plug into wall power if on a laptop.
+3. Run several times — the median-of-medians should settle within a few
+   percent across consecutive invocations.
+
+If your numbers diverge significantly from the reference table on similar
+hardware, please file an issue with the JSON output attached.

benchmarks/bench.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/* VELLA SDK — MIT License — Copyright (c) 2026 Vella Cognitive, LLC
+ *
+ * Latency benchmark for the Node SDK.
+ *
+ * Methodology:
+ *   - Warmup phase to stabilize JIT and resolve hot paths.
+ *   - K independent runs of N samples each. Per-run percentiles, then
+ *     median-of-medians across runs as the headline metric.
+ *   - GC quiesced between runs (requires --expose-gc; passed via run.sh).
+ *   - Ephemeral ECDSA P-256 signing key for the with-proof scenario.
+ *   - Timer is process.hrtime.bigint() (nanoseconds, monotonic).
+ *
+ * Usage:
+ *   node --expose-gc benchmarks/bench.js                  # human-readable
+ *   node --expose-gc benchmarks/bench.js --json           # JSON only
+ *   node --expose-gc benchmarks/bench.js --quick          # smaller N for sanity check
+ */
+
+import crypto from "node:crypto";
+import os from "node:os";
+import { govern } from "../sdk/node/index.js";
+
+const args = new Set(process.argv.slice(2));
+const QUICK = args.has("--quick");
+const JSON_ONLY = args.has("--json");
+
+const RUNS = 11;
+const DECISION_INNER = QUICK ? 10_000 : 100_000;
+const PROOF_INNER = QUICK ? 1_000 : 10_000;
+const WARMUP_DECISION = QUICK ? 1_000 : 10_000;
+const WARMUP_PROOF = QUICK ? 200 : 2_000;
+
+function ephemeralSigningKeyPem() {
+  const { privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+  return privateKey.export({ format: "pem", type: "pkcs8" });
+}
+
+function quantiles(samples) {
+  const sorted = Float64Array.from(samples);
+  sorted.sort();
+  const at = (q) => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))];
+  let sum = 0;
+  for (let i = 0; i < sorted.length; i++) sum += sorted[i];
+  return {
+    min: sorted[0],
+    p50: at(0.5),
+    p95: at(0.95),
+    p99: at(0.99),
+    max: sorted[sorted.length - 1],
+    mean: sum / sorted.length,
+  };
+}
+
+function median(arr) {
+  const s = [...arr].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+
+function runScenario(label, callable, { warmup, inner }) {
+  for (let i = 0; i < warmup; i++) callable();
+
+  const p50s = [];
+  const p95s = [];
+  const p99s = [];
+  let firstRunQuantiles = null;
+
+  for (let r = 0; r < RUNS; r++) {
+    if (typeof global.gc === "function") global.gc();
+
+    const samples = new Float64Array(inner);
+    for (let i = 0; i < inner; i++) {
+      const t0 = process.hrtime.bigint();
+      callable();
+      const t1 = process.hrtime.bigint();
+      samples[i] = Number(t1 - t0); // nanoseconds
+    }
+
+    const q = quantiles(samples);
+    p50s.push(q.p50);
+    p95s.push(q.p95);
+    p99s.push(q.p99);
+    if (r === 0) firstRunQuantiles = q;
+  }
+
+  return {
+    label,
+    runs: RUNS,
+    warmup,
+    iterations_per_run: inner,
+    median_of_medians_ns: {
+      p50: median(p50s),
+      p95: median(p95s),
+      p99: median(p99s),
+    },
+    sample_run_ns: firstRunQuantiles,
+  };
+}
+
+function fingerprint() {
+  const cpu = os.cpus()[0];
+  return {
+    cpu_model: cpu?.model ?? "unknown",
+    cpu_count: os.cpus().length,
+    arch: os.arch(),
+    platform: os.platform(),
+    release: os.release(),
+    node_version: process.version,
+    gc_exposed: typeof global.gc === "function",
+    quick: QUICK,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function fmtUs(ns) {
+  return (ns / 1000).toFixed(2) + "µs";
+}
+
+function main() {
+  const fp = fingerprint();
+  if (!fp.gc_exposed && !JSON_ONLY) {
+    process.stderr.write(
+      "warning: GC not exposed. Re-run with `node --expose-gc` for cleaner numbers.\n",
+    );
+  }
+
+  const signingKey = ephemeralSigningKeyPem();
+
+  const decisionOnly = runScenario(
+    "decision-only",
+    () => govern({ intent: "EXECUTE_CHANGE", evidenceMask: 1 }),
+    { warmup: WARMUP_DECISION, inner: DECISION_INNER },
+  );
+
+  const withProof = runScenario(
+    "with-proof",
+    () => govern({ intent: "EXECUTE_CHANGE", evidenceMask: 1, proof: { signingKey } }),
+    { warmup: WARMUP_PROOF, inner: PROOF_INNER },
+  );
+
+  const output = {
+    runtime: "node",
+    fingerprint: fp,
+    results: [decisionOnly, withProof],
+  };
+
+  if (JSON_ONLY) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  console.log("VELLA Node SDK — latency benchmark");
+  console.log("───────────────────────────────────");
+  console.log(`CPU      : ${fp.cpu_model} (${fp.cpu_count} threads, ${fp.arch})`);
+  console.log(`Platform : ${fp.platform} ${fp.release}`);
+  console.log(`Node     : ${fp.node_version}`);
+  console.log(`GC       : ${fp.gc_exposed ? "exposed (quiesced between runs)" : "NOT exposed"}`);
+  console.log("");
+  for (const r of output.results) {
+    console.log(
+      `[${r.label}]  runs=${r.runs}  N=${r.iterations_per_run}  warmup=${r.warmup}`,
+    );
+    console.log(
+      `  median-of-medians:  p50=${fmtUs(r.median_of_medians_ns.p50)}  p95=${fmtUs(r.median_of_medians_ns.p95)}  p99=${fmtUs(r.median_of_medians_ns.p99)}`,
+    );
+    console.log(
+      `  first run sample :  min=${fmtUs(r.sample_run_ns.min)}  p50=${fmtUs(r.sample_run_ns.p50)}  p99=${fmtUs(r.sample_run_ns.p99)}  max=${fmtUs(r.sample_run_ns.max)}`,
+    );
+    console.log("");
+  }
+  console.log("(JSON: re-run with --json)");
+}
+
+main();