OikosBot

Measures what software costs — in money, time, energy and carbon — and which repositories turn that spend into verified capability.

OikosBot analyses code and CI history through an ecological and economic lens. It is unusual in two ways: it treats the economic axes as seriously as the ecological ones, and it starts from Pareto optimality rather than a single score — a change is an improvement only if it dominates, and a trade-off is named as a trade-off.

Note

This repository is only OikosBot, and it is easy to confuse with two similarly-named-but-separate things: oikos — the stock-flow consistent economics DSL, now in hyperpolymath/oikos-economics-accounting-dsl. sustainabot — a reserved member slot of hyperpolymath/gitbot-fleet (bots/sustainabot/), to be prototyped later. OikosBot is not sustainabot; the implementation that briefly lived there was a misfiled copy of OikosBot and has been moved into this repo. See DISAMBIGUATION.adoc for the full breakdown.

Table of Contents

• Documentation
• Two units of analysis
• Status
• Repository Layout
• Data Layer
• Local Checks
• GitHub Action
• Estate analysis
• GitHub App
• Licence

Documentation

For a map of all documentation — grouped by audience (developer / maintainer / end-user) and by concept — see docs/README.adoc.

Two units of analysis

OikosBot works at two scales, and they have very different evidential strength.

	Per file (analyze / check / report / compare)	Per estate (estate collect / analyse / report)
Question	Did this change dominate its base, or trade off?	Which repositories turn spend into verified capability — and which consume input and produce none?
Inputs	tree-sitter AST metrics	GitHub CI telemetry: billable minutes, wall-clock, runner class
Confidence	Estimated only	Measured money and time; Calibrated energy; Estimated carbon
Can it block?	No — see the caveat below	Not yet; round one is read-only by design

The estate view exists because allocative efficiency is not a property of a single change. It means scarce resources flow to their highest-valued competing use; with one diff in front of you there is nothing to allocate between. Opportunity cost and marginal analysis need a portfolio, so the portfolio is the unit.

Status

v0.1.0 — online in CI/Action mode; estate pipeline shipped, read-only. Full picture: docs/STATUS.adoc (human), STATE.a2ml (machine), and DEBT.adoc (what is owed).

Working: the Pareto engine (crates/oikosbot-pareto), the estate pipeline (oikosbot-telemetry / -capability / -dea), the published container ghcr.io/hyperpolymath/oikos, the composite GitHub Action, .oikos.yml configuration, and SARIF output that GitHub code scanning ingests.

Important

Per-file resource figures are heuristic estimates and --check cannot block a merge. Only Measured/Calibrated inputs may fail a run, and the analyser emits only Estimated — calibration exists but is not yet wired in (issue \#48). OikosBot warns loudly rather than passing silently, but treat the per-file verdict as an advisor, not a regulator. The estate path is the exception: wall_minutes comes straight from the GitHub API and is genuinely Measured. See DEBT.adoc for the full account of what is and is not earned.

The Rust analysis workspace (crates/oikosbot-*: CLI, analysis engine, metrics, Pareto engine, SARIF output, and Eclexia policy evaluation) builds and tests cleanly and is the most complete surface — it was extracted from the former gitbot-fleet/bots/sustainabot/ and renamed.

The AffineScript webhook receiver (bot-integration-affine/) is a scaffold. HMAC-SHA256 webhook signature verification is implemented in bot-integration-affine/src/Webhook.affine (constant-time, via the hpm-crypto RSR FFI), and the upstream AffineScript standard-library prerequisites have landed (json RSR rewire, affinescript#421; Http server RSR rewire, affinescript#425). The webhook → analyse → comment orchestration is now wired in source (src/Payload.affine extracts the PR fields and handle_github_webhook runs Oikos.handle_pr_event); what remains is binding the HTTP listener (Sub.http_server), which is gated on the stdlib Http::Server host type. (The AffineScript changes are unverified — there is no AS toolchain in this environment.)

The Haskell analyzer scaffold (analyzers/code-haskell/) builds independently.

Repository Layout

oikosbot/
|-- crates/ # Rust workspace (oikosbot-* analysis engine + CLI)
| |-- oikosbot-cli/ # `oikosbot` binary (analyze/check/report/compare/estate)
| |-- oikosbot-analysis/ # tree-sitter analysis + eco/econ heuristics
| |-- oikosbot-metrics/ # shared metric/result types + confidence ladder
| |-- oikosbot-pareto/ # epsilon-tolerant dominance, frontier, verdicts
| |-- oikosbot-telemetry/ # estate: gh-API collector, parquet snapshots, derived metrics
| |-- oikosbot-capability/ # estate: verified-capability output metrics
| |-- oikosbot-dea/ # estate: Data Envelopment Analysis (CCR/BCC LPs)
| |-- oikosbot-sarif/ # SARIF report generation
| |-- oikosbot-eclexia/ # Eclexia (.ecl) policy evaluation
| `-- oikosbot-fleet/ # OPTIONAL gitbot-fleet bridge (excluded by default)
|-- bot-integration-affine/ # AffineScript webhook receiver (in flight)
|-- analyzers/code-haskell/ # Haskell eco/econ/quality analysis engine
|-- policy-engine/ # Datalog and DeepProbLog policy rules
|-- policies/ # Eclexia (.ecl) policy definitions
|-- config/oikos.yaml # Bot configuration
|-- databases/ontology/ # eco.ttl — VeriSimDB semantic-witness ontology seed
|-- examples/ # Example CI integration
|-- fuzz/ # cargo-fuzz targets (excluded from the workspace)
|-- docs/ # documentation map, status, setup guides, specs
|-- ARCHITECTURE.adoc # Platform architecture (TARGET design — see DEBT.adoc)
|-- DEBT.adoc # Debt register: licence / docs / code / proof / CI-CD
|-- DISAMBIGUATION.adoc # oikos vs OikosBot vs sustainabot
|-- QUICKSTART.adoc # CLI quickstart
`-- DEPLOY.adoc # Deployment status and runbook notes

Data Layer

OikosBot persists analysis results, code-relationship graphs, and the eco/econ knowledge base in a single identity-consonance store, VeriSimDB. In VeriSimDB one identity is an octad of modal witnesses — graph, vector, tensor, semantic, document, temporal, provenance, spatial. The graph + document witnesses take over the role once planned for ArangoDB (code-dependency graphs, analysis history, project metadata), and the semantic witness takes over the role once planned for Virtuoso/RDF (ontology knowledge, proof blobs). The eco/econ ontology seed for the semantic witness lives at databases/ontology/eco.ttl.

VeriSimDB is v0.1.0 and OikosBot’s runtime client is deferred: the data layer is retargeted in design and configuration now (see config/oikos.yaml and ARCHITECTURE.adoc), with runtime wiring tracked on the roadmap. The legacy ArangoDB + Virtuoso assets were retired (recoverable in git history).

Local Checks

cargo build --workspace # or: just rust-build
cargo test --workspace # or: just rust-test
just haskell-build
just haskell-test
just affine-check

The default cargo workspace deliberately excludes crates/oikosbot-fleet (the optional gitbot-fleet bridge) so OikosBot builds standalone. See DISAMBIGUATION.adoc.

just affine-check expects an AffineScript compiler. Override the compiler path with AS_BIN=/path/to/main.exe when needed.

GitHub Action

OikosBot runs in CI as a composite action wrapping the published container (ghcr.io/hyperpolymath/oikos):

- uses: hyperpolymath/oikosbot@main # pin a tag/SHA in productionwith:
mode: report # report | check | comparepath: .output: results.sarif # upload with github/codeql-action/upload-sarif

compare mode issues a Pareto verdict against a base checkout (see QUICKSTART). A repo-local .oikos.yml is honored automatically. Full workflow example: examples/oikosbot-ci.yml.

How OikosBot relates to the nearest Marketplace neighbour: OikosBot vs Climate Warrior.

Estate analysis

Treats a whole GitHub organisation as a portfolio competing for one budget of minutes, money, energy and carbon.

oikosbot estate collect --owner <org> --out <staging> [--max-runs 200]
oikosbot estate analyse --staging <staging> --snapshot <dir>
oikosbot estate report --snapshot <dir> [--format md|json] [-o FILE]

collect reads CI run history through the authenticated gh CLI — no instrumentation in the measured repos, and it works retroactively. It is resumable: a staging file that already exists is skipped, so an interrupted sweep can simply be re-run.

analyse derives per-repo cost and capability, then runs Data Envelopment Analysis — input-oriented CCR and BCC solved as linear programs. DEA compares units with multiple incommensurable inputs and outputs, needs no prices, and returns three things: an efficiency score, the peer set (which frontier repos this one is measured against — an exemplar, not just a number), and the LP duals, which are shadow prices derived from the estate’s own data.

The output measure is verified capability, not activity: does a workflow parse, can a gate actually fail, do artefacts publish. That reframes a familiar pathology as an economic one — a repository burning CI minutes on a gate with hundreds of successes and no failure in its entire history is consuming real input for no verified output.

Snapshots are versioned Parquet committed to a separate dataset repository, hyperpolymath/oikosbot-estate, so history is git history and the analysis never silently measures a corpus containing itself. Two analyse runs over the same staging produce byte-identical output.

Note	Round one is deliberately read-only: it reports, it does not gate. The premise was checked before anything was built on it — measured correlation between compute time and code volume across 381 repositories is −0.049, i.e. the axes really are independent rather than one variable in disguise.

GitHub App

The app manifest lives at .github/app.yml. The setup guide is docs/GITHUB_APP_SETUP.adoc.

Licence

MPL-2.0. See LICENSE.