@iowarp/clio-coder 0.4.6 → 0.4.8

package/docs/process/release-cut-checklist.md

@@ -1,219 +1,116 @@
 # Release-Cut Checklist
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Release-Cut Checklist visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/release_checklist_blueprint.html).
-
-This document provides the standard procedure for cutting a release of Clio Coder.
-Releases are cut from an annotated tag on canonical main. The GitHub release is
-produced by GitHub Actions, while package publication to npm is an authorized manual
-step performed by a maintainer. Everything before the authorization boundary is local,
-repeatable, and reversible. Every step following the authorization boundary affects
-canonical remote state or publishes immutable packages.
-
-## Part 1: Candidate Preparation on a Local Compact Branch
-
-Maintainers prepare release candidates on a local-only compact branch named after
-the version without punctuation, such as `v046` for version `0.4.6`. Dotted branch
-names like `v0.4.6` are forbidden because dotted names belong exclusively to immutable
-tags. The canonical repository hosts only `main`, and no release candidate branch is
-ever pushed to canonical origin.
-
-1. Ensure the working tree is clean and updated from canonical origin:
-
-   ```bash
-   git checkout -b v046 origin/main
-   ```
-
-2. Update `version` in `package.json` and `assets/acp-registry/agent.json` to the
-   release version. Update the README's source-install tag and remove any
-   development-only notices. Keep historical release records, protocol schema
-   versions, dependency versions, and migration fixtures unchanged.
-
-3. Retitle the active changelog section in `CHANGELOG.md` from `## Unreleased` to
-   `## <version> - YYYY-MM-DD`. The release gate in `scripts/check-release.mjs` requires
-   the first version header to match the version in `package.json`.
-
-4. Commit the release candidate preparation locally:
-
-   ```bash
-   git commit -am "chore(release): prepare <version>"
-   ```
-
-## Part 2: Local Candidate Verification Gate
-
-Run deterministic local checks on the candidate commit before requesting authorization.
-
-1. Execute the release gate:
-
-   ```bash
-   pnpm run ci:release
-   ```
-
-   This gate runs `pnpm run ci` followed by `node scripts/check-release.mjs`. It verifies
-   type checking, Biome formatting, hygiene rules, architecture boundary invariants,
-   the build, the contract and smoke test suites, trace-viewer tests, and dist integrity.
-   The packaging audit checks executable entry shebangs, ensures forbidden files like
-   source maps and caches are omitted, verifies runtime resources from `scripts/release-manifest.json`,
-   and enforces size limits (10 MB packed, 50 MB unpacked).
-
-2. Optionally validate a live model turn against a configured target:
-
-   ```bash
-   node dist/cli/index.js run --target <id> --autonomy read-only "Reply with exactly: CLIO_LIVE_OK"
-   ```
-
-3. Run the real-home smoke test against the operator configuration:
-
-   ```bash
-   pnpm run smoke:real-home --target <id> --strict
-   ```
-
-   This runs `scripts/smoke-real-home.sh` using a copy of operator settings in a scratch
-   `CLIO_CODER_HOME`. The `--strict` flag ensures any failing rows from `clio-coder doctor`
-   fail the smoke run.
-
-4. Inspect the npm package contents with a dry run:
-
-   ```bash
-   npm pack --dry-run
-   ```
-
-5. Validate an installed tarball in a clean temporary directory:
-
-   Create a temporary directory, pack the tarball, install it via npm, and verify
-   installed binary lifecycle commands in an isolated environment with an empty `CLIO_CODER_HOME`:
-
-   ```bash
-   clio-coder --version
-   clio-coder --help
-   clio-coder doctor
-   clio-coder uninstall --dry-run
-   ```
-
-## Part 3: Candidate Review and Authorization Boundary
-
-Before touching any remote ref, summarize the candidate for maintainer review:
-- Candidate commit SHA
-- Results of `pnpm run ci:release`
-- Verification output from real-home smoke and installed package testing
-- Changelog contents and target npm version
-
-Every step below changes canonical remote refs, creates a release, or publishes
-an immutable package. Do not execute any of them without explicit maintainer authorization.
-
-## Part 4: Fast-forward Canonical Main
-
-1. Fetch the latest remote status from origin:
-
-   ```bash
-   git fetch origin
-   ```
-
-2. Confirm `origin/main` is an ancestor of the local candidate branch.
-
-3. Fast-forward local `main` to the candidate commit:
-
-   ```bash
-   git checkout main
-   git merge --ff-only v046
-   ```
-
-4. Verify that local `main` matches the reviewed candidate SHA exactly.
-
-5. Push `main` to canonical origin:
-
-   ```bash
-   git push origin refs/heads/main:refs/heads/main
-   ```
-
-   No release branch is ever pushed to origin.
-
-## Part 5: Tagging and GitHub Release
-
-1. Wait for GitHub Actions CI on canonical `main` to finish green for the pushed SHA.
-
-2. Create an annotated git tag matching the version:
-
-   ```bash
-   git tag -a v<version> -m "Clio Coder <version>"
-   ```
-
-3. Push only the release tag to canonical origin:
-
-   ```bash
-   git push origin refs/tags/v<version>
-   ```
-
-4. Pushing the tag triggers `.github/workflows/release.yml`. The workflow:
-   - Verifies the tag matches `package.json`.
-   - Runs `pnpm run ci:release` on the tagged commit.
-   - Packs the release tarball with `npm pack`.
-   - Extracts the version changelog section from `CHANGELOG.md`.
-   - Creates the GitHub Release with the tarball attached using `gh release create`.
-
-5. Inspect the GitHub Actions workflow run and confirm the GitHub release is published.
-
-6. Reconcile the release milestone against the tagged commits and each ticket's
-   acceptance evidence. `Fixes #123` or `Resolves #123` in a commit closes that
-   ticket when the commit reaches default-branch `main`; a bare `#123`, changelog
-   mention, tag, or GitHub release does not. Verify the resulting issue state.
-   Explicitly close completed tickets missed by automatic closure and retain
-   their implementing commit and validation references. Carry incomplete work
-   forward with its remaining criteria, then close the reconciled milestone.
-   Never infer completion from a release-note mention alone.
-
-## Part 6: Package Publication to npm
-
-Publishing to npm is a manual maintainer step performed from the tagged commit.
-
-1. Confirm authentication and registry status:
-
-   ```bash
-   npm whoami
-   ```
-
-2. Confirm the version does not already exist on npm:
-
-   ```bash
-   npm view @iowarp/clio-coder@<version>
-   ```
-
-3. Publish the package from the tagged checkout:
-
-   ```bash
-   npm publish
-   ```
-
-   The `prepublishOnly` lifecycle script sets `CLIO_CODER_RELEASE_CONTEXT=publish` and
-   re-executes `pnpm run ci:release` as a mandatory release-mode verification gate before
-   files are uploaded. When publishing a pre-release channel, append `--tag <channel>`.
-
-## Part 7: Post-Publish Verification and Branch Closeout
-
-1. Verify package availability on npm:
-
-   ```bash
-   npm view @iowarp/clio-coder version
-   ```
-
-2. On a clean machine, install the package globally and run basic lifecycle checks:
-
-   ```bash
-   npm install -g @iowarp/clio-coder@<version>
-   clio-coder --version
-   clio-coder doctor
-   ```
-
-3. Remove the local compact candidate branch:
-
-   ```bash
-   git branch -d v046
-   ```
-
-   The canonical repository remains in its steady state containing only `main` and immutable tags.
-
-## Part 8: Rollback and Error Recovery
-
-npm package publication is irreversible. A published version cannot be removed or overwritten.
-Any issue discovered after publication must be resolved through a subsequent release. Prior
-to pushing git tags or publishing to npm, local candidate commits can be amended or reset freely.
+Qualify one committed candidate and its exact npm tarball. Publication uses a fast
+preflight of that evidence. Development investigations are separate and are never
+implicitly repeated by a publish lifecycle hook.
+
+## Prepare locally
+
+1. Inspect `git status --short --branch`. Preserve operator work. Use one local
+   candidate branch; do not push main, candidate branches, or tags without authorization.
+2. Set the approved version in `package.json` and `assets/acp-registry/agent.json`,
+   date the matching top changelog section, and align the README install tag.
+3. Commit all candidate changes. Qualification refuses tracked or untracked source
+   changes. Ignored operator files are not candidate inputs; ignored `dist/` bytes
+   are verified through the actual npm package.
+4. Install once with `pnpm install --frozen-lockfile`. Record cold installation time
+   separately when comparing hosted gate times.
+
+## Qualify the candidate
+
+```bash
+pnpm run ci:release
+```
+
+This runs:
+
+- The routine gate: root types, lint/hygiene and library pins, one build, core
+  safety/session/provider/accounting/extension contracts, three real CLI/ACP/process
+  smoke files, and the web authentication and runtime boundary tests.
+- Web TypeScript checks and the shipped dependency advisory/package audit.
+- One exact npm tarball install with normal lifecycle scripts, installed resources,
+  lazy chunks, CLI and extension/library behavior, both web workers and a real Chrome
+  boot/reconnect against that installed server.
+- Native invocation timing with delayed real HTTP headers, durable call timing and
+  eval first-call selection.
+
+No real model, npm login or publication occurs. An unavailable registry or advisory
+service fails qualification. Chrome must be installed at `/usr/bin/google-chrome` on
+Linux. Windows subprocess semantics have a separate narrow CI lane; a Linux pass is
+not evidence of a full Windows or macOS pass.
+
+The command prints the qualified SHA, tarball path and SHA-256. Evidence lives outside
+the checkout under `~/.cache/clio-coder/qualification/<checkout-id>/`, bounded to one
+candidate per checkout. Starting qualification deletes the earlier receipt. A failed
+or cancelled run cannot leave an older qualification available for publication.
+Qualification also repacks after testing and refuses changed package bytes.
+
+Do not run the full suite, rebuild, repack for manual installation, or repeat the
+routine gate afterward. Relevant development regressions should be exercised while
+implementing the change, before qualifying the final committed candidate.
+
+## Review and authorize remote changes
+
+Present the exact commit, package digest, verification results and release notes.
+Every remote main/tag update, GitHub release and npm publication requires explicit
+maintainer authorization.
+
+After authorization, fetch origin, check that `origin/main` is an ancestor of the
+candidate, and fast-forward local main. Verify the SHA is unchanged. Fetch once more
+and stop on unexpected remote movement before pushing only main. After required CI
+passes for that SHA, create and push only the annotated version tag matching
+`package.json`. Never use a dotted release-tag name for a branch.
+
+A temporary `ci-scratch-*` branch is permitted only when explicitly authorized for
+hosted verification. Its CI runs candidate qualification. Delete that owned remote
+branch after inspection. Routine main/PR CI runs `pnpm run ci` as `ci (22)` and cancels superseded
+runs. The required `ci (24)` check tests only engine, provider and durable-session
+compatibility on the other supported Node major, without another build or full gate.
+
+## GitHub release
+
+The tag workflow qualifies the exact tagged source with read-only permissions. It
+uploads the tested tarball and checksum. A separate `release` job has `needs: qualify`,
+verifies the downloaded checksum and creates the release using the matching changelog
+section. Only that job has `contents: write`. Failure or cancellation of qualification
+prevents release creation. No retries, `continue-on-error`, independent repacking or
+npm publication are part of the workflow.
+
+## Publish after authorization
+
+From the unchanged locally qualified checkout, with the same Node version:
+
+```bash
+pnpm run release:preflight
+npm publish
+```
+
+`prepublishOnly` performs the same fast preflight. It checks the clean source SHA,
+Node version, qualification age (maximum 24 hours), original tarball digest, current
+npm package digest, and dated matching release notes. Current packaging includes
+ignored build output, so changing a chunk also invalidates the qualification. Missing,
+stale or changed inputs fail closed and require `pnpm run ci:release` again.
+
+Use normal npm authentication separately when publication is authorized. Confirm the
+version is available before publishing; do not log in or publish merely to test this
+pipeline. No `--ignore-scripts`, bypass flags or hand-authored "already tested" markers.
+
+Verify npm availability and installation after publication, reconcile completed and
+outstanding milestone issues, and close out the local candidate branch only after its
+work is proven on canonical main. Published tags are immutable.
+
+## Optional development investigations
+
+```bash
+pnpm run test:file -- tests/extended/<file>.test.ts
+pnpm run test:full
+pnpm run test:web:full
+pnpm --filter @iowarp/clio-coder-web verify
+pnpm run smoke:real-home -- --target <configured-target-id> --strict
+```
+
+The full root/web suites, browser viewport/accessibility matrix, live models, native
+host interoperability and operator-home checks support development and investigations.
+They are not publication gates. Keep scratch outside the checkout, bound it, clean it,
+and retain subprocess ownership until children settle. Never move an unresolved
+correctness failure out of a required gate to obtain a green release.

package/docs/process/scientific-validation.md

@@ -1,8 +1,5 @@
 # Clio Coder Scientific Validation Contracts
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Scientific Validation Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/validation_blueprint.html).
-
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
 Clio Coder recognizes a **scientific validation contract** as an opt-in signal for a higher evidence bar. One strict loader in `src/domains/safety/validation-contract.ts` reads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root and parses it under the version-1 schema below. A contract that parses raises the default rigor level to `high`. A contract that does not parse (empty, malformed YAML, unknown field, unsupported version, over the 256 KiB cap) leaves rigor at `normal` and is diagnosed with the exact fault: `clio-coder doctor` reports it in the `validation contract` row, the interactive session prints it once at startup, and `clio-coder verifiers author` repeats it. A Markdown `VALIDATION.md` is recognized as present but is never parsed and never raises rigor on its own; it is advisory prose for developers, project agents, and external validators.
@@ -122,3 +119,26 @@ Clio Coder integrates scientific validation contracts directly into its safety m
 - **High-Rigor Gate Requirements**: Once the rigor is `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The window is entries since the last user message, capped at 80 entries:
   - Clio issues a `request_continuation` middleware effect to keep the session running.
   - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to call `limitation` before it can conclude the turn.
+
+## Verification boundaries and limitation receipts
+
+File readback establishes artifact inspection, not executed scientific validation. When an agent or worker modifies files but cannot execute the outstanding checks with its admitted tools and approved scope:
+
+1. **The generic `limitation` tool**:
+   - Clio provides the pure canonical `limitation` tool (`src/tools/limitation.ts`), recording a `limitation` tool_call and tool_result receipt in the session ledger.
+   - Arguments:
+     - `scope` (required string): What could not be verified, in one sentence.
+     - `reason` (required enum): One of `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`.
+     - `paths` (optional array of strings): Repository-relative file paths left unverified.
+   - A prose disclaimer or text summary in conversation is not a limitation receipt; only a successful `limitation` tool call registers a typed receipt in the session ledger.
+
+2. **Recipe instructions vs generic harness**:
+   - Bundled scientific recipes (such as Materio research agents in `library/plugins/materio`) explicitly instruct workers via `<clio_verification_boundary>` in their recipe bodies to call `limitation` when external checks cannot run. This boundary instruction is authored recipe content, not an unconditional harness envelope injected into every worker.
+
+3. **Finish gate enforcement**:
+   - At high rigor (such as when a valid `validation.yaml` contract is present), the finish gate monitors workspace mutations within the recent active turn window (up to 80 entries since the last user message).
+   - If mutating tool calls occurred in that window without executed validation evidence or a `limitation` receipt, `finishContractRegistration` (`src/domains/safety/finish-contract-registration.ts`) emits a `request_continuation` middleware effect accompanied by a reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`). At normal rigor, it emits an advisory reminder without blocking.
+   - The gate checks structural evidence presence; it does not grade the empirical correctness of scientific code. Runtime turn budgets, deadline limits, operator cancellation, and tool failures still apply.
+   - A limitation receipt never converts missing or failing checks into a pass; it formally records the limitation so callers and operators know the scientific result is incomplete.
+   - Verified by contracts `tests/extended/materio-plugin.test.ts` and `tests/extended/safety-policy-remediation.test.ts`.
+

package/evals/scalar-decision-machinery.ts

@@ -24,7 +24,7 @@ if (!python) throw new Error("Pass an existing Python interpreter with NumPy; th
 const fixture = JSON.parse(readFileSync(new URL("./fixtures/scalar-decision.json", import.meta.url), "utf8"));
 const grader = fileURLToPath(new URL("./scalar-decision-grader.py", import.meta.url));
 const { restore } = await isolateClioEnv();
-const root = mkdtempSync(join(tmpdir(), "clio-scalar-decision-"));
+const root = mkdtempSync(join(tmpdir(), "clio-coder-scalar-decision-"));
 
 function grade(source: string, value: string) {
 	const policy = value === fixture.pythonPolicy ? "python-int" : value === fixture.numpyPolicy ? "numpy-integer" : null;

package/examples/extensions/README.md

@@ -0,0 +1,67 @@
+# Local scientific extensions
+
+These installable examples use the harness extension lifecycle, separately from
+library recipes. They require a Clio build containing operator runtime API v1.
+The manifests retain the current package compatibility minimum, 0.4.7; use this
+implementation or a later release that includes it (the original 0.4.7 release
+predates the runtime field).
+
+From the repository root:
+
+```bash
+clio-coder extensions discover examples/extensions/lab-status --json
+clio-coder extensions install examples/extensions/lab-status --project
+clio-coder extensions run lab-status dashboard
+clio-coder extensions run lab-status dashboard --json
+```
+
+In Clio, reload through `/extensions reload`, then invoke
+`/ext:lab-status:dashboard`. Core renders the panel, owns scrolling and Escape,
+and displays the status with the extension's owner label. The default record is
+`jobs.synthetic.json`: **SYNTHETIC FIXTURE**, two completed jobs and one running
+job. These are deterministic demonstration records, not measured cluster facts.
+
+Pass a local JSON record filename as the argument to inspect your own data:
+
+```bash
+clio-coder extensions run lab-status dashboard -- /absolute/path/experiment.json
+```
+
+The record has `experiment` and `jobs` fields. Each job supplies a string `id`,
+positive integer `ranks`, `state` (`queued`, `running`, `completed`, `failed`) and
+nonnegative finite `elapsedSeconds`. Set `synthetic: true` for simulated data.
+Records without that marker are labeled local reported data, not independently
+verified results. Files are regular local files up to 32 KiB and at most 100 jobs.
+The example performs no SSH, scheduler query, submission, provider request or
+credential access. Turn observations repeat the last explicit snapshot; invoke
+the dashboard again to refresh the file. Runtime state resets on reload.
+
+The separate measurement package keeps the existing model tool contract:
+
+```bash
+clio-coder extensions install examples/extensions/measurements --project
+```
+
+Start a new session. The admitted model tool is
+`extension_measurements__summarize`, with input such as
+`{"values":[1,2,3],"units":"seconds"}`. That input is a **synthetic deterministic
+example**, with mean 2 and sample standard deviation 1. A one-value input returns
+`null` for sample standard deviation. Numeric overflow errors instead of
+reporting null or invented valid measurements. Execution still passes the tool
+registry's safety, autonomy and approval rules. Native worker recipes must
+explicitly admit the qualified tool. Installing a runtime never adds tools to
+existing model schemas.
+
+Update source, reinstall with `--force`, then reload operator runtimes at idle.
+Disable and remove exact copies with `--project` or `--user`:
+
+```bash
+clio-coder extensions disable lab-status --project
+clio-coder extensions enable lab-status --project
+clio-coder extensions remove lab-status --project
+```
+
+Do not edit installed package bytes in place. Whole-tree digest drift revokes
+calls; mixed tool/UI packages need a new session even when only UI bytes change.
+Installed runtime code has your account's filesystem/network authority. A child
+process gives bounded teardown and fresh module caches, not an OS sandbox.

package/examples/extensions/lab-status/clio-coder-extension.json

@@ -0,0 +1,14 @@
+{
+	"id": "lab-status",
+	"name": "Local experiment status",
+	"version": "1.0.0",
+	"description": "Inspect a local experiment record; default data is explicitly synthetic.",
+	"compatibility": { "clio": ">=0.4.7" },
+	"runtime": {
+		"api": 1,
+		"entrypoint": "extension.mjs",
+		"commands": [{ "name": "dashboard", "description": "Show synthetic jobs or a named local JSON experiment file." }],
+		"events": ["session_open", "turn_end"],
+		"ui": ["status", "panel"]
+	}
+}

package/examples/extensions/lab-status/extension.mjs

@@ -0,0 +1,68 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+
+let lastStatus = { text: "Synthetic fixture available; invoke dashboard", tone: "neutral" };
+async function readRecord(file) {
+	const handle = await open(file, "r");
+	try {
+		const info = await handle.stat();
+		if (!info.isFile() || info.size > 32768) throw new Error("Expected a regular local JSON record, at most 32 KiB");
+		const buffer = Buffer.alloc(32769);
+		const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+		if (bytesRead > 32768) throw new Error("Experiment record exceeds 32 KiB");
+		const data = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
+		if (
+			typeof data.experiment !== "string" ||
+			data.experiment.length > 120 ||
+			!Array.isArray(data.jobs) ||
+			data.jobs.length > 100
+		)
+			throw new Error("Invalid experiment record");
+		for (const job of data.jobs) {
+			if (
+				typeof job.id !== "string" ||
+				job.id.length > 80 ||
+				!["queued", "running", "completed", "failed"].includes(job.state) ||
+				!Number.isInteger(job.ranks) ||
+				job.ranks < 1 ||
+				!Number.isFinite(job.elapsedSeconds) ||
+				job.elapsedSeconds < 0
+			)
+				throw new Error("Invalid job record");
+		}
+		return data;
+	} finally {
+		await handle.close();
+	}
+}
+/** @param {import('@iowarp/clio-coder/extensions').ExtensionApi} api */
+export default function extension(api) {
+	api.handle("dashboard", async (args, context) => {
+		const file = args.trim()
+			? path.resolve(context.snapshot.workspace, args.trim())
+			: new URL("./jobs.synthetic.json", import.meta.url);
+		const data = await readRecord(file);
+		context.signal.throwIfAborted();
+		const label = data.synthetic === true ? "SYNTHETIC FIXTURE" : "LOCAL RECORD (reported, not independently verified)";
+		const completed = data.jobs.filter((job) => job.state === "completed").length;
+		lastStatus = { text: `${label}: ${completed}/${data.jobs.length} completed`, tone: "neutral" };
+		const rows = data.jobs.map((job) => [job.id, String(job.ranks), job.state, String(job.elapsedSeconds)]);
+		return {
+			text: `${label}\n${data.experiment}\n${completed}/${data.jobs.length} completed\n${rows.map((row) => row.join(" | ")).join("\n")}\nSource: ${file}`,
+			status: lastStatus,
+			panel: {
+				title: data.experiment,
+				sections: [
+					{
+						kind: "text",
+						text: `${label}\nSource: ${file}\nThis extension reads records only. It never submits or queries cluster jobs.`,
+					},
+					{ kind: "metrics", items: [{ label: "Completed", value: `${completed}/${data.jobs.length}` }] },
+					{ kind: "table", columns: ["Job", "MPI ranks", "State", "Elapsed s"], rows },
+				],
+			},
+		};
+	});
+	api.on("session_open", () => ({ text: "", status: lastStatus }));
+	api.on("turn_end", () => ({ text: "", status: lastStatus }));
+}

package/examples/extensions/lab-status/jobs.synthetic.json

@@ -0,0 +1,9 @@
+{
+	"synthetic": true,
+	"experiment": "Synthetic stencil scaling fixture",
+	"jobs": [
+		{ "id": "fixture-1", "ranks": 8, "state": "completed", "elapsedSeconds": 42 },
+		{ "id": "fixture-2", "ranks": 16, "state": "completed", "elapsedSeconds": 24 },
+		{ "id": "fixture-3", "ranks": 32, "state": "running", "elapsedSeconds": 9 }
+	]
+}

package/examples/extensions/measurements/clio-coder-extension.json

@@ -0,0 +1,28 @@
+{
+	"id": "measurements",
+	"name": "Measurement summary",
+	"version": "1.0.0",
+	"description": "Count, mean, min, max and sample standard deviation of supplied finite measurements.",
+	"compatibility": { "clio": ">=0.4.7" },
+	"capabilities": {
+		"tools": [
+			{
+				"name": "summarize",
+				"description": "Summarize supplied measurements without inventing physical units or provenance.",
+				"runtime": "node",
+				"entrypoint": "summarize.cjs",
+				"timeoutMs": 10000,
+				"maxOutputBytes": 16384,
+				"inputSchema": {
+					"type": "object",
+					"properties": {
+						"values": { "type": "array", "items": { "type": "number" }, "minItems": 1, "maxItems": 1000 },
+						"units": { "type": "string", "maxLength": 40 }
+					},
+					"required": ["values"],
+					"additionalProperties": false
+				}
+			}
+		]
+	}
+}

package/examples/extensions/measurements/summarize.cjs

@@ -0,0 +1,23 @@
+const { values, units } = JSON.parse(process.argv[2]);
+if (!Array.isArray(values) || values.length < 1 || values.length > 1000 || !values.every(Number.isFinite))
+	throw new Error("Expected 1-1000 finite measurements");
+let mean = 0;
+let m2 = 0;
+for (const [index, value] of values.entries()) {
+	const delta = value - mean;
+	mean += delta / (index + 1);
+	m2 += delta * (value - mean);
+}
+if (!Number.isFinite(mean) || !Number.isFinite(m2))
+	throw new Error("Numerical overflow; rescale the supplied measurements");
+console.log(
+	JSON.stringify({
+		count: values.length,
+		mean,
+		min: Math.min(...values),
+		max: Math.max(...values),
+		sampleStandardDeviation: values.length > 1 ? Math.sqrt(m2 / (values.length - 1)) : null,
+		units: units ?? null,
+		source: "caller-supplied measurements; provenance not independently verified",
+	}),
+);