CodeSampleX

# CodeSampleX

> **Tested. Not guessed.**

<p align="center">
  <img src="internal/web/static/inspector-hero-v1.webp" alt="CodeSampleX compatibility inspector" width="560">
</p>

**Languages:** [English](README.md) · [한국어](docs/i18n/README.ko.md) · [日本語](docs/i18n/README.ja.md) · [简体中文](docs/i18n/README.zh-CN.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Deutsch](docs/i18n/README.de.md) · [Português (BR)](docs/i18n/README.pt-BR.md) · [Русский](docs/i18n/README.ru.md)

CodeSampleX is an **open compatibility testing network** for developer libraries, runtimes and toolchains. It does not summarize documentation and it does not collect anecdotes: it runs real builds and contract tests in real, recorded environments — then shows you where things actually worked, where they broke, and how sure it is of both.

- Compatibility map: **https://codesamplex.dev**
- The question it answers: *does it run there?* — this API, on this version, on this OS, under this runtime.
- The answer it gives: *we tested it; this is what happened.*

## Does it run there?

Every result is a recorded execution with its environment attached, so the data pivots into compatibility matrices — OS × runtime, version × architecture, symbol × OS. A real slice, from the live network (`axios.post`, measured August 2026):

```text
axios.post · axios 1.12.2                node 22          node 24
linux                                    ✓ PASS verified     —
windows                                  ○ 3/9 observed ! ?  (process runs: 3 pass · 6 fail)
```

That row is not an illustration — it is [the live page](https://codesamplex.dev/npm/axios/1.12.2/axios.post). `PASS` on linux is a contract that executed in a pinned container; the windows cell is honest about being weaker evidence (`○` observed with the `?` uncertainty marker — build observations, not a contract run) and about its measured failures (`!`). Unknown stays `—`; nothing is inferred from the package's ecosystem or its docs.

The web explorer treats every 2D grid as a slice of an N-dimensional cube: pick any two dimensions as axes (OS, runtime, package version, symbol, architecture, package manager, execution context, libc), pin the rest as filters, and click a cell to drill one level deeper — down to the exact measured combinations, whose symbol pages hold the signed receipts.

## Why testing matters

```text
Documentation   → what should work
Code search     → how somebody used it
Community       → what somebody says worked
CodeSampleX     → what was actually tested
```

The rules that keep the map honest:

- A project compiling is **never** presented as a symbol working. Observations and verifications are counted separately and never summed.
- Unknown causes stay `UNKNOWN`. A wrong HIT is worse than a MISS — `NO_SAFE_MATCH` is a real answer.
- Evidence decays: a result's weight halves every 90 days, and stale cells say so.
- Failure causes are reported as probability distributions, never invented certainties.

## Install the CLI

The CLI is the local tester: it wraps your real builds, turns their outcomes into anonymous evidence, and answers from the network.

Windows (PowerShell):

```powershell
irm https://codesamplex.dev/install.ps1 | iex
```

macOS / Linux:

```bash
curl -fsSL https://codesamplex.dev/install.sh | sh
```

That line needs `curl` and CA certificates, which minimal images (debian-slim, alpine, most agent containers) do not have — and `curl … | sh` **exits 0 when curl is missing**, because a pipeline reports the last command's status. Install prerequisites first, or use wget:

```bash
apt-get install -y curl ca-certificates            # debian / ubuntu slim
apk add --no-cache curl ca-certificates            # alpine
wget -qO- https://codesamplex.dev/install.sh | sh  # needs neither
```

The binary lands in `~/.local/bin`, which is on nobody's `PATH` by default:

```bash
export PATH="$HOME/.local/bin:$PATH"
csx version    # the install check — `csx --version` is not a spelling csx accepts
```

One binary, one question. `csx init` shows the contract below and asks a single choice — **JOIN COMMUNITY** or **LOCAL ONLY**. Piped into `sh`, stdin is consumed by the download pipe, so `init` takes the advertised default: JOIN COMMUNITY. Opt out any time with `csx init --local-only`; both mode flags are re-runnable and non-interactive. For scripted or CI setups: `csx init --community --yes --no-agents`.

## Test and check

```bash
csx run -- pnpm build              # wrap any build/test — its result becomes evidence
csx search "axios multipart upload"  # a verified answer, graded for YOUR environment
csx scan                           # record which public packages a project uses, no build
csx stats                          # local dashboard: hits, adoptions, queue
csx ui                             # browser dashboard + privacy preview
csx sync                           # warm the shard cache — once, right after install
```

`csx sync` is not optional garnish: a fresh install has zero shards cached, so every search returns `NO_SAFE_MATCH` until it syncs. The daemon re-warms in the background afterwards.

`csx search` grades every result against your recorded environment — `EXACT`, `COMPATIBLE`, `ADAPTATION_REQUIRED`, `REFERENCE_ONLY`, or `NO_SAFE_MATCH` — and lists the exact delta (`different`, `adaptationNeeded`) between where the answer was proven and where you are.

## Verified samples

A sample is not a snippet. It is a minimal, content-addressed project (`sha256:<hex>` of its canonical artifact) with a **contract**: assertions that were executed offline in a pinned container and passed. The clean-room authoring loop is CLI-only:

```bash
csx sample propose --goal "upload a file with axios"   # sanitized brief, empty workspace
csx sample create <dir>      # ingest the clean-room project
csx sample verify <id>       # resolve → compile → contract, sandboxed
csx sample publish <id>      # requires typing exactly "yes"; leakage findings hard-refuse
```

Publishing scans for secrets, paths, project names and private URLs — findings **block** publication with no override flag. Uploading sample source is deliberately not an MCP capability; only a human at the CLI can publish.

## Findings

Where does it break? [Findings](https://codesamplex.dev/findings) is the measured contradiction list: what the documentation (or common belief) says, next to what the contract measured — documentation mismatches, environment-specific failures, version boundaries. Every line links to the published sample whose contract proves it, so you can re-run the measurement and disagree.

Machine-derived findings grow from published samples whose authors recorded the belief they correct; nobody edits a page to add them.

## Evidence and grading

Why trust a cell? Every result carries its evidence class, weak → strong:

| Grade | What actually happened |
|-------|------------------------|
| `USAGE_OBSERVATION` | a real project built/typechecked/tested with the package — observed, weak |
| `ADOPTION_EVIDENCE` | someone applied a sample and reported whether the build then passed |
| `SAMPLE_VERIFICATION` | the sample's contract executed in a pinned container and passed |
| `CROSS_PASS` | an independent peer re-ran it and it passed again |
| `MATRIX_PASS` | passing runs span ≥2 OS/runtime/browser boundaries |
| `STABLE` | ≥3 independent peers pass it, no failure recorded for 30 days |

Sample pages also badge the verification ladder `L0_SOURCE_ONLY` → `L5_MATRIX_PASS`, and matrix cells carry confidence (`HIGH`/`MEDIUM`/`LOW`), elevated-failure flags, and last-seen dates. Only signed **v2 receipts** may claim `resolvedPackages` — the versions the verifier actually installed, not the versions an author typed; snapshots file each receipt under the version that really ran.

The public counters are a rollup, available as JSON without an account:

```bash
curl -fsSL https://codesamplex.dev/v1/stats
```

| Field | What it counts |
|-------|----------------|
| `packages` / `symbols` | coverage: public package names and observed symbols in the compatibility data |
| `evidence` | accepted observation records; not users, projects, or verified samples |
| `verifiedSamples` | distinct samples with a sandbox contract-PASS receipt |
| `peers` / `projectsMonth` | distinct anonymous daily/monthly contributor buckets |
| `postHitBuildsReported` | adoption reports that included a measured PASS or FAIL |

CodeSampleX does **not yet measure reliable unique/active users, live MCP processes, or successful installs**. Any `estimated*` field in the stats response is explicitly formula-based and must not be read as a measured count.

## Contributor worker

The network's environments are other people's machines. A spare one can contribute Docker-isolated verification without touching MCP or agent config:

```bash
csx init --community --yes --no-agents --no-daemon
csx worker start                         # idle-aware, 2 Docker lanes
csx worker start --parallel 4 --budget 15m
```

The worker accepts only server-assigned VERIFY jobs (`cross` / `matrix`) — the queue never sends an arbitrary shell command. Artifacts are content-addressed and hash-checked; resolve is containerized; compile and contract stages run network-off in disposable Docker workspaces with fixed `512m` memory / `256` PID limits; a missing Docker daemon is a hard refusal, never a host fallback. Results are ed25519-signed v2 receipts; raw stage logs stay local. See [Contribute](https://codesamplex.dev/contribute).

## API

The same data the website renders, as JSON, without an account:

| Endpoint | What it serves |
|----------|----------------|
| `GET /v1/stats` | the daily network rollup |
| `POST /v1/search`, `POST /v2/search` | graded answers for a query + environment fingerprint |
| `GET /v1/registry/packages/{purl}` | package detail + package-level snapshot |
| `GET /v1/registry/symbols/{eco}/{package}/{family}` | per-version snapshots f