{
  "markdown": "# Project Bourne\n\n[![project-bourne MCP server](https://glama.ai/mcp/servers/KozakHou/project-bourne/badges/card.svg)](https://glama.ai/mcp/servers/KozakHou/project-bourne)\n\nProject Bourne is open-source execution and provenance infrastructure for\nreproducible scientific and engineering workloads.\n\nIt answers: **Exactly how did this scientific result come to exist?**\n\n## Keep AI off the cluster\n\n~~~text\nResearcher's workstation\n  Linux / macOS\n        │\n  AI / Agent (optional)\n        │ local stdio MCP\n        ▼\n  Bourne Control Plane\n        │\n        ├─ freezes immutable ExecutionPlan\n        ├─ builds/stages versioned Bourne workers\n        └─ uses existing VPN / OpenSSH\n        ▼\n\nHPC login / access node\n  one-shot Bourne Remote Worker\n        │\n        ├─ validates the plan\n        ├─ verifies staged file digests\n        ├─ stages the execution bundle\n        └─ submits with sbatch / qsub / bsub\n        ▼\n\nSlurm / PBS / IBM LSF\n        │\n        │ allocates resources\n        ▼\n\nCompute allocation\n  execution-scoped Bourne Compute Worker\n        │\n        ├─ reads immutable ExecutionPlan\n        ├─ observes actual allocation\n        ├─ reproduces selected environment\n        ├─ performs compute-side preflight\n        ├─ executes exact scientific argv\n        └─ writes durable result evidence\n        ▼\n\nScientific workload\n\nLater:\n\nResearcher's workstation\n        │\n        │ existing SSH\n        ▼\nRemote Worker: reconcile\n        │\n        ├─ exact Bourne-owned scheduler job state\n        └─ bounded result evidence\n        ▼\nLocal Bourne provenance database\n~~~\n\nThe Remote Worker and Compute Worker are not agents or persistent services;\nboth are short-lived, versioned Bourne workers. Bourne does not SSH directly\ninto compute nodes. Slurm/PBS/LSF places the Compute Worker inside the allocation\nand owns job lifetime after accepting the submission. The researcher's\nworkstation / control plane may disconnect and reconcile the same execution\nlater.\n\nThe HPC path requires no AI, MCP server, AI credential, inbound port, root\naccess, persistent daemon, or public-internet access on the cluster. It uses\nthe researcher's existing OpenSSH configuration and scheduler access. Agents\nreceive typed Bourne operations—not an unrestricted remote shell.\n\nThe Bourne control plane is supported and tested on Linux and macOS. Native\nWindows is not yet validated or supported.\n\nBourne remains agent-native, not agent-dependent. The CLI and Python services\nwork without an agent or MCP.\n\n## Quick Start\n\n### Human\n\nInstall Project Bourne v0.8.1 from PyPI:\n\n~~~bash\npython -m pip install \"bourneprov==0.8.1\"\n\nbourne run python examples/demo.py\nbourne list\nbourne show @1\n\n# Or execute an ExecutionRequest v2 document:\nbourne execute --request bourne.json\n~~~\n\nConfigure a site-aware SSH workflow with the installed CLI:\n\n~~~bash\nbourne site add imperial \\\n  --ssh login.example.edu \\\n  --scheduler slurm \\\n  --local-root \"$PWD\" \\\n  --remote-root /work/$USER/project\n\nbourne discover --site imperial\nbourne plan --site imperial --request bourne.json --provider constraints.json\n~~~\n\nThe first plan call prints bounded candidates. A human or agent then makes the\npreference decision explicitly:\n\n~~~bash\nbourne plan --site imperial --request bourne.json \\\n  --provider constraints.json \\\n  --trust-provider-classifications \\\n  --candidate sha256:...\n\nbourne execute --plan <plan-id>\nbourne execution wait <execution-id>\n~~~\n\nThe trust flag is an explicit review decision for semantic classifications in\nthat declarative provider; the provider cannot grant itself that authority.\nUse `--approve-variant-change PARAMETER` or\n`--declare-execution-only PARAMETER` for narrower user decisions. If the\nselected candidate changes a provider-bound JSON input, Bourne preserves the\noriginal and automatically binds a separately hashed `WorkloadVariant` to the\nplan.\n\nSlurm/PBS/LSF owns the job after acceptance. The researcher's workstation /\ncontrol plane, VPN, SSH connection, MCP host, and agent may disconnect; Bourne\nreconnects later and reconciles the exact execution. An ambiguous connection\nfailure never triggers blind resubmission.\n\n### Agent / MCP\n\nThe v0.8.1 agent and MCP entrypoints remain local stdio:\n\n~~~bash\npython -m pip install \"bourneprov[mcp]==0.8.1\"\nbourne mcp\n\n# Or use the public transparent launcher:\nnpx -y @project-bourne/mcp@0.8.1\n~~~\n\n## Development\n\nProject Bourne uses `uv` as its development, dependency-locking, test, and\nbuild frontend. After installing uv, synchronize the committed lockfile and run\nthe suite with:\n\n~~~bash\nuv sync --locked --all-extras --dev\nuv run --frozen --no-sync python -W error::ResourceWarning -m unittest discover -s tests -v\nuv build --no-sources\n~~~\n\nCI uses locked/frozen variants of these commands so an out-of-date `uv.lock`\nfails instead of drifting. uv is development tooling only: it is not a\n`bourneprov` runtime dependency, is not required for `pip install`, is not\nused by the npm launcher, and is never required on HPC login or compute nodes.\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for the complete contributor workflow.\n\n## Why Bourne\n\nBourne wraps arbitrary executables without requiring changes to the scientific\nprogram. It is local-first and framework-agnostic: Python, compiled solvers,\nJulia, MPI programs, and other commands use the same durable experiment model.\n\n~~~bash\nbourne run bash -c \"echo hello\"\nbourne run ./solver case.yaml\nbourne run julia simulation.jl\nbourne run mpirun -np 64 ./solver\n~~~\n\nProgram stdout and stderr remain visible during execution and are preserved in\nthe experiment record.\n\n## Runtime truth in v0.8\n\nv0.8 keeps planning truth, scheduler truth, runtime truth, experiment truth,\nverification, and scientific validity separate. The execution-scoped Compute\nWorker records versioned process, allocation, CPU, memory, I/O, GPU, and\nenvironment evidence with explicit `observed`, `partially_observed`,\n`unavailable`, `unsupported`, or `unknown` coverage. Missing telemetry does not\nfail a valid workload and never becomes a fabricated zero.\n\nIBM LSF joins Slurm and PBS with bounded queue discovery, `bsub`, exact-job\nactive `bjobs`, recent-finished `bjobs -a`, durable `bhist` reconciliation,\nand `bkill`. Existing\nApptainer/Singularity images can be frozen into a selected site-aware plan;\nBourne verifies the existing runtime/image on the compute side and passes the\nscientific command as exact argv. It does not build, pull, install, or manage\nimages. v0.8 does not orchestrate multi-node container launch, choose\nMPI-launcher/container ordering, or inject an MPI launcher. See\n[runtime evidence and scheduler coverage](docs/RUNTIME_EVIDENCE.md).\n\n## Core architecture\n\nBourne Core owns deterministic execution, evidence, planning, storage, and\nprovenance. CLI, SDK, and MCP are adapters over the same services:\n\n~~~text\n             Project Bourne Core\n                    │\n       ┌────────────┼────────────┐\n       │            │            │\n      CLI          SDK          MCP\n    humans                     agents\n~~~\n\nThe remote worker is one-shot, user-space, non-AI, and non-daemon. It accepts\nonly versioned operations for discovery, plan validation, staging, scheduler\nsubmission, and reconciliation. Scientific commands remain exact argv in an\nimmutable plan; no scientific argv is interpolated into remote shell text.\nThe remote-worker protocol remains v1. v0.8 adds worker-result protocol v3 and\nstaged-plan protocol v4 while retaining readers for released worker-result\nv1/v2 and staged-plan v1/v2/v3 payloads.\n\n## Agent and MCP Integration\n\nThe canonical local stdio server is `bourne mcp`. The stable official MCP\nRegistry identity is `io.github.KozakHou/project-bourne`, and the portable\nAgent Skill is at [`skills/project-bourne`](skills/project-bourne). The v0.8.1\nnpm package and matching Registry metadata use the same release identity.\n\nAn MCP-compatible agent can translate an explicit request such as “Run this\nsimulation using four GPUs and preserve provenance” into ExecutionRequest v2,\nask Bourne to plan it, show the deterministic resolution, and execute the\nimmutable plan after execution intent is established. Bourne itself does not\ninterpret unconstrained natural language and does not call another model.\n\nThe agent path is deliberately two-phase:\n\n~~~text\nagent intent → ExecutionRequest v2 → bourne_plan → inspect → bourne_execute_plan\n~~~\n\nPlanning never runs the workload or silently discovers infrastructure.\nAmbiguous targets and unknown facts remain unresolved. MCP annotations are host\nUX hints; Bourne Core still enforces immutable plans, exact argv, scheduler job\nownership, artifact semantics, and provenance. See [MCP integration](docs/MCP.md)\nand [Agent guidance](docs/AGENTS.md).\n\n## Execution Requests\n\nAn execution can now be described once in a bounded, versioned JSON request:\n\n~~~json\n{\n  \"kind\": \"bourne.execution-request\",\n  \"version\": 2,\n  \"command\": [\"python\", \"train.py\", \"--case\", \"case1\"],\n  \"artifacts\": {\n    \"inputs\": [\"config.yaml\"],\n    \"outputs\": [\"result.h5\"]\n  },\n  \"resources\": {\"cpus\": 8, \"gpus\": 1, \"walltime\": \"2h\"},\n  \"execution\": {\"backend\": \"direct\"},\n  \"verification\": {\n    \"checks\": [\n      {\"type\": \"output_exists\", \"path\": \"result.h5\"},\n      {\"type\": \"output_min_bytes\", \"path\": \"result.h5\", \"min_bytes\": 1024}\n    ]\n  }\n}\n~~~\n\nSave it as `bourne.json`, then use the same intent for planning or execution:\n\n~~~bash\nbourne request validate bourne.json\nbourne request show bourne.json\n\nbourne discover\nbourne plan --request bourne.json\nbourne execute --request bourne.json\n~~~\n\nCreate a minimal request without executing or discovering anything:\n\n~~~bash\nbourne request init --output bourne.json -- python train.py\nbourne request schema > execution-request-v2.schema.json\n~~~\n\nExisting flag-based commands remain supported. They compile into the same\n`ExecutionRequest → WorkloadSpec → ExecutionPlan` pipeline rather than a\nparallel implementation:\n\n~~~bash\nbourne execute --backend direct --cpus 2 --output result.txt -- python script.py\n~~~\n\nFor a request file, a relative `working_directory` is resolved from the\nrequest file's directory. Declared artifacts are then resolved from that\nscientific working directory. Bourne preserves both the lexical and resolved\nworking-directory values and does not expand `$HOME`, evaluate shell syntax,\nimport project code, or execute anything while parsing or planning.\n\nParent references follow the same intent-preserving rule. A request may use\n`latest`, `@N`, a unique prefix, or a full ULID. Bourne retains that requested\nvalue while separately recording the canonical parent ULID used by the compiled\nworkload.\n\nSummary telemetry is enabled by default and uses already captured facts: wall\ntime, UTF-8 stdout/stderr byte counts, known artifact byte totals, requested\nresources, observed allocation, and scheduler queue timing when timestamps\nestablish it. `\"telemetry\": {\"mode\": \"off\"}` disables the summary. Missing\nmetrics remain unavailable, never zero.\n\nThe initial deterministic verification checks are `output_exists`,\n`output_min_bytes`, and `output_sha256`. They evaluate only captured declared\noutput `Artifact` records. Verification is persisted separately from process\nstatus: an experiment may be `completed` while verification is `failed` or\n`unknown`. These checks establish artifact facts, not general scientific\nvalidity. See [Execution requests, telemetry, and verification](docs/EXECUTION_REQUESTS.md)\nfor the exact contract and safety limits.\n\n## Planning and Execution\n\nProject Bourne v0.4.0 adds a durable planning layer over v0.3 inventories:\n\n~~~bash\nbourne discover\n\nbourne plan --backend direct -- python examples/demo.py\nbourne execute --backend direct -- python examples/demo.py\n\nbourne execution list\nbourne execution show @1\n~~~\n\n`bourne plan` never runs the scientific command and never performs discovery.\nIt creates a framework-independent `WorkloadSpec`, compares its explicit and\ninferred requirements with an existing inventory, explains every candidate,\nand persists an immutable `ExecutionPlan` only when selection is unambiguous.\nUse explicit resource and placement constraints when needed:\n\n~~~bash\nbourne plan \\\n  --backend slurm \\\n  --target gpu \\\n  --cpus 16 \\\n  --gpus 4 \\\n  --nodes 1 \\\n  --memory 64G \\\n  --walltime 2h \\\n  -- ./solver case.yaml\n~~~\n\nExecute a selected Slurm plan and then inspect or wait for the resulting\nexecution attempt:\n\n~~~bash\nbourne execute --plan @1\nbourne execution show @1\nbourne execution wait @1\n~~~\n\nWhile a recorded job is still active, `bourne execution cancel @1` requests\ncancellation of that Bourne-managed job. The same planning and lifecycle model\nsupports `--backend pbs` and `--backend lsf`.\n\nDirect execution reuses Bourne's existing live-output, process-group, artifact,\nlineage, and experiment-provenance machinery. Slurm, PBS, and LSF plans use a\nself-contained Bourne worker staged with the plan. The worker performs\npreflight and records the actual allocated host and scientific experiment;\nthe access-side controller imports its bounded JSON result transactionally.\nNo compute-node SSH or preinstalled `bourneprov` package is required, although\nthe compute allocation must provide Python 3 and visibility of the staging and\nworking directories.\n\nSubmission is not an experiment, scheduler completion is not scientific\nsuccess, and requested resources are not allocated resources. Bourne records\nthese as separate durable facts. Cancellation accepts a Bourne execution\nreference—not an arbitrary scheduler job ID—and checks the submitting identity.\nSee [Workload planning and scheduler execution](docs/WORKLOAD_EXECUTION.md) for\nthe exact model, safety boundary, and current limitations.\n\n## Compute-site discovery (v0.3.0)\n\nBourne can take an immutable, local snapshot of the execution surface visible\nto your current identity:\n\n~~~bash\nbourne discover\nbourne inventory\nbourne inventory --find python\nbourne inventory --json\n~~~\n\nDiscovery covers the current identity and access target, allow-listed\nuser-relevant storage paths, direct execution contexts, generic PATH\nexecutables, optional Conda/virtualenv/container/module contexts, safe system\ncapabilities, Bourne history, and read-only Slurm/PBS/LSF target-class summaries\nwhen available. An unknown executable is recorded generically without being\nrun. Laptops, desktop and GPU workstations, DGX-class personal machines, shared\nlaboratory systems, and scheduler-backed HPC sites are all valid compute\nsites. A scheduler-free machine is complete in its own right.\n\nDiscovery is observational: an executable is not verified workload\ncompatibility, a visible scheduler partition is not proof of submission\nauthorization, and a storage role hint is not a retention or backup policy.\nInventories remain local. Providers do not traverse other users' homes, crawl\nshared storage, inspect SSH credentials or container secrets, dump arbitrary\nenvironment variables, SSH into compute nodes, submit or cancel scheduler\njobs, or modify environments. See [Compute-site discovery](docs/COMPUTE_SITE_DISCOVERY.md)\nfor the exact topology, evidence, limits, and security semantics.\n\n## Provenance, Artifacts and Lineage\n\nProject Bourne v0.2 adds explicit input/output fingerprints, a minimal\nderived_from relationship, safe execution-context observations, and artifact\ntracing. Run the deterministic example from an isolated directory:\n\n~~~bash\ncp -R examples/provenance /tmp/bourne-provenance-demo\ncd /tmp/bourne-provenance-demo\nexport BOURNE_DB=\"$PWD/bourne.sqlite3\"\n\nbourne run \\\n  --input config_A.json \\\n  --output result_A.csv \\\n  -- python demo_simulation.py config_A.json result_A.csv\n\nbourne run \\\n  --derived-from @1 \\\n  --input config_B.json \\\n  --input result_A.csv \\\n  --output result_B.csv \\\n  -- python demo_simulation.py config_B.json result_B.csv\n\nbourne show @2\nbourne show @1\nbourne trace result_B.csv\n~~~\n\nInputs are fingerprinted before execution. Outputs are fingerprinted afterward,\nincluding expected outputs that are missing after a failed or interrupted run.\nSHA-256 reads are streamed in chunks; Bourne does not copy or upload declared\nfiles.\n\nA path is not artifact identity. Each capture has a stable ULID, while SHA-256\ndistinguishes content versions. When a historical path could identify several\nversions and the current file content cannot disambiguate them, bourne trace\nlists candidates and refuses to guess.\n\nSee [Artifacts, lineage, and execution context](https://github.com/KozakHou/project-bourne/blob/main/docs/ARTIFACTS_AND_LINEAGE.md)\nfor exact capture, trace, migration, and security semantics.\n\n## Human-friendly experiment references\n\nCanonical experiment identities remain 26-character ULIDs. Commands that\naccept an experiment also understand:\n\n~~~text\n01M02GDJEW...   case-insensitive unique ULID prefix\nlatest          most recent experiment\n@1              most recent experiment\n@2              second-most-recent experiment\n@3              third-most-recent experiment\n~~~\n\nFor example:\n\n~~~bash\nbourne show latest\nbourne show 01M02GDJEW\nbourne compare @2 @1\nbourne run --derived-from @1 -- ./solver case_B.yaml\n~~~\n\nBourne never guesses when a prefix is ambiguous. bourne list displays a\n10-character prefix by default; bourne list --full-id displays canonical IDs.\n\n## Shell completion\n\nCompletion candidates include canonical experiment IDs, latest, and recent @N\nreferences. Activate completion for the current shell session with:\n\n~~~bash\n# Bash\nsource <(bourne completion bash)\n\n# Zsh\nsource <(bourne completion zsh)\n\n# Fish\nbourne completion fish | source\n~~~\n\nCompletion for bourne show and bourne compare queries the currently configured\ndatabase, including BOURNE_DB.\n\n## What Bourne records\n\nEvery experiment records:\n\n- execution status (completed, failed, or interrupted), exact argument vector,\n  working directory, UTC timestamps, duration, and exit code;\n- live and captured stdout/stderr;\n- Git repository root, commit, branch, and dirty state when available;\n- operating system, architecture, hostname, CPU, and optional NVIDIA runtime\n  metadata;\n- requested and resolved executable paths plus strictly allow-listed\n  virtualenv/Conda context hints;\n- explicitly declared input/output artifact versions and immediate lineage.\n\nCollectors degrade gracefully. Missing Git, NVIDIA tooling, GPUs, environment\nhints, or executable resolution does not stop the workload. Arbitrary\nenvironment variables are not persisted, so credentials and tokens are not\ncaptured by default.\n\nFailed and interrupted commands are saved before bourne returns their process\nsemantics:\n\n~~~bash\nbourne run --output expected.csv -- python -c \"raise RuntimeError('boom')\"\nbourne show @1\n~~~\n\nOn POSIX systems, Bourne uses a dedicated process group so Ctrl+C normally\nterminates descendants without targeting unrelated processes.\n\nExecution success is not verification, and deterministic artifact verification\nis not general scientific validity. Bourne records these states separately.\n\n## Local storage and migration\n\nThe default SQLite path is:\n\n~~~text\n~/.local/share/bourne/experiments.sqlite3\n~~~\n\nUse a project-specific database with:\n\n~~~bash\nexport BOURNE_DB=/path/to/experiments.sqlite3\n~~~\n\nOpening an older Bourne database, including released v0.1.1 through v0.7.0\ndatabases, with v0.8.0 performs deterministic transactional migrations\nthrough schema 7.\nExisting experiments, artifacts, lineage, inventories, workloads, plans,\nexecutions, scheduler jobs, allocations, events, and experiment links remain\nreadable. Migration does not invent `ExecutionRequest` history for v0.4\nrecords. Unknown or newer schema versions fail explicitly; Bourne never resets\nan existing database. Each new discovery creates a separate immutable\nsnapshot.\n\n## License\n\nProject Bourne v0.5.0 and later are distributed under the\n[Apache License 2.0](LICENSE). Releases through v0.4.0 remain under the MIT\nLicense terms under which they were released. See the\n[licensing history](docs/LICENSING.md) for details.\n\n## Release validation\n\nThe release version is `0.8.1`. The base runtime has zero third-party\ndependencies; MCP support remains an explicit optional extra.\n\nRun the source-tree tests with:\n\n~~~bash\nuv sync --locked --all-extras --dev\nuv run --frozen --no-sync python -W error::ResourceWarning -m unittest discover -s tests -v\nuv build --no-sources\n~~~\n\nCompute-worker stdout and stderr remain live and are bounded to 8 MiB per\ncaptured stream in the result bundle; truncation is explicit runtime evidence.\nOrdinary local `bourne run` retains its existing capture behavior. Disk-spooled\nlogs, automatic artifact discovery/archival, scientific dependency\ninstallation or source builds, generic data synchronization, unrestricted\nremote shell, scheduler-free disconnect-safe remote supervision, whole-allocation distributed\ntelemetry, queue/performance prediction, arbitrary verification scripts,\nhosted HTTP MCP, embedded LLMs, and broad scientific-validity inference remain\noutside v0.8. See [runtime evidence and scheduler coverage](docs/RUNTIME_EVIDENCE.md),\n[the site-aware architecture](docs/SITE_AWARE_PLANNING.md), and [VISION](docs/VISION.md).\n\nLive LSF and live Apptainer validation have not yet been performed. Runtime\nsampling is execution-scoped and does not automatically aggregate across a\nmulti-node allocation. Bourne does not inject MPI launchers or automatically\nchoose container/MPI ordering. Portable LSF memory/GPU resource syntax remains\nsite-specific and unresolved.\n",
  "bytes": 21510,
  "sha": "429be2ee8ff86fafab80ee8733cf948d222488f5e6e290e16271e62bca429449",
  "repo_slug": "kozakhou/project-bourne",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kozakhou_project_bourne_1bf50f16/readme"
}