Evidence and contribution

Evidence & contribution

GenOS is ambitious enough that documentation discipline is part of the product. Contributions should make the system more executable, more falsifiable, or clearer about its boundary.

Current maturity

The v0.0.1 baseline includes executable local foundations:

• typed genomes, phenotype, state, beliefs, evidence, and causal records;
• local snapshots, capsules, event stores, and content-addressable artifacts;
• directory and Git-oriented world providers;
• snapshot, restore, fork, diff, merge, lineage, and replay mechanics;
• evaluation, heredity, branch-evolution, and memory research primitives;
• a unified CLI, initial MCP server, schemas, and transport tests;
• GenOS Studio and a local backend.

The next developer-preview target focuses on a coherent capsule-first workflow, persistence, provider connectors, cleanup and cancellation, schema stability, installation, and developer experience.

Later roadmap milestones cover integrated biomimetic swarms, a causal evaluation laboratory, hardened distributed storage, microVM isolation, cluster orchestration, compliance attestation, and production support. These are targets, not current guarantees.

High-value ways to contribute

Strengthen a proof

• turn a design claim into a focused test;
• add a deterministic cross-platform fixture;
• publish raw benchmark samples with machine metadata;
• implement an external runtime adapter with equivalent inputs;
• reproduce a result independently and document the revision.

Close an isolation or replay gap

• model external tool receipts and replay classes;
• improve cleanup of temporary worlds;
• add process/network sandbox adapters;
• test failure, cancellation, timeout, and partial-result salvage;
• document exactly which state is captured by each snapshot type.

Improve developer experience

• reduce quickstart friction;
• make CLI errors actionable;
• stabilize schemas and migration paths;
• improve Studio navigation and route coverage;
• add end-to-end examples that need no provider credentials.

Extend the research surface carefully

• add controlled cohorts for genome/phenotype experiments;
• connect branch evolution to a live evaluator;
• validate cognitive merge conflict policies;
• improve claim provenance and contradiction handling;
• test Pareto policies with transparent objective definitions.

Contribution workflow

1. Choose a focused issue or define a falsifiable problem.
2. Create a branch using a repository prefix such as feat/, fix/, docs/, exp/, perf/, refactor/, or chore/.
3. Add source, tests, and documentation in the same change when behavior changes.
4. Run the applicable formatting, lint, tests, and reproducibility checks.
5. Open a pull request with summary, motivation, exact verification commands, observed results, and any breaking change.

Substantial protocol, storage, security-boundary, or crate-level changes should use the RFC/ADR process before implementation.

Claim discipline

Before writing “deterministic”, “isolated”, “secure”, “faster”, “cheaper”, or “production-ready”, answer:

• What exact boundary does the claim cover?
• Is it implemented or only designed?
• Which test or command reproduces it?
• What revision and environment were used?
• Are raw results available?
• What is explicitly not covered?
• Has anyone independent reproduced it?

Use the evidence ladder from Examples & evidence. Unsupported metrics remain unsupported; missing runs remain missing.

Local verification

For a broad Rust change, start with:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

Then run the focused example or benchmark that corresponds to the claim. A broad test suite does not replace scenario-specific evidence.

Security reports

Do not open a public issue for a suspected vulnerability, sandbox escape, credential leak, CAS integrity problem, or remote-code-execution path. Follow SECURITY.md and GitHub's private vulnerability reporting flow.

Governance and license

GenOS is licensed under Apache 2.0. Governance, code of conduct, support, and contribution documents live at the repository root. The project is pre-alpha; compatibility guarantees begin only when explicitly declared by a release.