File size: 11,869 Bytes

1d3f990

# Contributing to ROWM

**Version:** 1.0.0  
**Status:** Open for Contributions  
**Authors:** Ahmad Ali Parr, Jessica SNAPKITTYWEST

---

## Welcome

ROWM is an open-source project seeking contributors in:
- **Formal verification** (Agda, Ada/SPARK, Lean 4 integration)
- **Language support** (new polyglot parsers)
- **Performance optimization** (VM speed, compilation)
- **Security auditing** (threat model review, penetration testing)
- **Documentation** (guides, examples, API docs)
- **Testing** (unit tests, integration tests, property-based tests)

---

## Core Values

1. **Logic Over Assumptions** — Every claim is backed by Prolog facts
2. **Evidence Over Assertions** — No feature ships without passing tests
3. **Reproducibility Over Convenience** — Build and test results must be deterministic
4. **Transparency Over Secrecy** — Threat model and known limitations are public
5. **Verification Over Belief** — Formal proofs preferred over documentation

---

## Getting Started

### Prerequisites

- Rust 1.78+ (install via [rustup.rs](https://rustup.rs))
- GNU M4 (for morphing engine)
- SWI-Prolog 8.x+ (for logic engine)
- Git

### Build

```bash

git clone https://github.com/SNAPKITTYWEST/rowm-polymorphic-notebook.git

cd rowm-polymorphic-notebook

cargo build --release --workspace

```

### Run Tests

```bash

# Rust tests

cargo test --all --lib



# Prolog tests

swipl -f logic/facts/*.pl -f logic/rules/*.pl -f logic/queries/test_queries.pl -t run_tests



# Release readiness check

swipl -f logic/facts/*.pl -f logic/rules/*.pl -t "release_ready(R), format('Result: ~w~n', [R])."

```

---

## Development Workflow

### 1. Pick an Issue

Check [GitHub Issues](https://github.com/SNAPKITTYWEST/rowm-polymorphic-notebook/issues) for:
- Bugs with `#audit` label (security/correctness)
- Features with `#feature` label
- Docs with `#documentation` label

### 2. Create a Branch

```bash

git checkout -b fix/issue-name  # for bug fixes

git checkout -b feature/issue-name  # for new features

git checkout -b docs/issue-name  # for documentation

```

### 3. Implement & Test

- Write code following project style (see below)
- Add tests for all new functionality
- Run full test suite: `cargo test --all --lib`
- Verify Prolog logic: `swipl ...` queries

### 4. Commit with Evidence

Include concrete evidence in commit message:

```

fix: Authorization gate now properly rejects tier_2 agents



Fixes #42: dispatch_gated/5 now checks agent_trust_level before returning true.

Boundary condition: Timestamp < ExpiresAt (not <=).



Evidence:

- Test case: test_tier2_agent_dispatch_denied passes

- Regression: test_expired_capability_acceptance now correctly fails

- Prolog validation: readiness_check('no_revoked_capabilities', true) passes



Co-Authored-By: Claude <noreply@anthropic.com>

```

### 5. Create Pull Request

```bash

git push origin feature/issue-name

gh pr create --fill

```

Include in PR description:
- What this fixes (or adds)
- How to test it
- Relevant documentation changes
- Any known limitations

### 6. Review & Merge

- Address code review feedback
- Re-run tests after changes
- Maintain focus on single issue (don't add unrelated fixes)
- Once approved: repo maintainers merge

---

## Code Style

### Rust

- Use `cargo fmt` before committing: `cargo fmt --all`
- Use `cargo clippy` for linting: `cargo clippy --all --lib`
- **No unsafe code** without explicit `// SAFETY: ...` comment explaining why
- Prefer `Result<T>` over panicking for errors
- Max line length: 100 characters (soft limit)

**Example:**

```rust

// Good: explicit error handling

pub fn load_proof(path: &str) -> Result<ProofTerm> {

    let bytes = std::fs::read(path)?;

    serde_json::from_slice(&bytes).map_err(|e| anyhow!("Invalid proof: {}", e))

}



// Avoid: panicking

pub fn load_proof_bad(path: &str) -> ProofTerm {

    serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap()

}

```

### Prolog

- One fact per line (no multi-line facts)
- Comments above rules explaining intent
- Use descriptive predicate names (not `p/2`, use `authorization/2`)
- No anonymous variables (`_`) in public predicates

**Example:**

```prolog

% Good: clear, documented

% dispatch_gated/5: Sealed authorization entry point

% All external dispatch must pass through this predicate.

dispatch_gated(Agent, Cap, Runtime, Perm, true) :-

    agent_active(Agent, true),

    agent_trust_level(Agent, Tier),

    Tier \= tier_2,

    capability_issued(Cap, _, Agent, Runtime, Perms, _, Expires),

    \+ capability_revoked(Cap, _),

    get_time(Now),

    Now < Expires,

    member(Perm, Perms),

    runtime_active(Runtime, true).



% Avoid: cryptic

p(A, C, R, P, T) :- a(A), tnl(A, TL), TL \= t2, ci(C, _, A, R, PS, _, E), 

    \+ cr(C, _), gt(N), N < E, m(P, PS), ra(R, T).

```

### Documentation (Markdown)

- Use ATX headers (`#`, `##`, not underlines)
- Wrap at 80 characters for readability
- Include code examples with language tags
- Link to related documentation and GitHub issues

---

## Testing

### Unit Tests

Write tests in `#[cfg(test)]` modules:

```rust

#[cfg(test)]

mod tests {

    use super::*;



    #[test]

    fn test_dispatch_gated_rejects_revoked_capability() {

        // Arrange

        let agent = "forge";

        let cap = "capa_revoked";

        let runtime = "rust";

        let permission = "execute";



        // Act

        let result = dispatch_gated(agent, cap, runtime, permission, ?);



        // Assert

        assert_eq!(result, false);

    }

}

```

### Integration Tests

Add files to `crates/*/tests/`:

```rust

// tests/integration_test.rs

#[test]

fn test_end_to_end_cell_execution() {

    // Full execution: parse → authorize → compile → execute → verify → receipt

}

```

### Prolog Tests

Add to `logic/queries/test_queries.pl`:

```prolog

test_dispatch_gated_denies_tier2 :-

    \+ dispatch_gated('phantom', 'capa_001', rust, execute, true),

    write('✓ Tier 2 agent correctly denied\n').

```

### Property-Based Tests

Use `proptest` for randomized testing:

```rust

proptest! {

    #[test]

    fn prop_invariant_preserved(seed in 0u64..1000) {

        let mut vm = create_test_vm(seed);

        vm.execute().expect("execution must succeed");

        assert!(check_all_invariants(&vm));

    }

}

```

---

## Merge Criteria

Before a PR can merge, all of the following must pass:

- [ ] **Build:** `cargo build --release --workspace` succeeds
- [ ] **Tests:** `cargo test --all --lib` passes (100%)
- [ ] **Linting:** `cargo clippy` has no warnings
- [ ] **Format:** `cargo fmt` produces no changes
- [ ] **Prolog:** `swipl ... release_ready(true)` passes
- [ ] **Documentation:** Relevant docs updated
- [ ] **Evidence:** Commit message includes test evidence
- [ ] **No Security Regressions:** No removal of authorization checks
- [ ] **No Unstaged Features:** No proto/planned code merged as complete
- [ ] **Reviewed:** At least 1 approving review from maintainer

---

## Adding a New Language to Polyglot Frontend

### Step 1: Implement Parser Trait

```rust

// crates/polyglot-frontend/src/parsers/mylang.rs

pub struct MyLangParser;



impl Parser for MyLangParser {

    fn parse(&self, source: &str) -> Result<Ast> {

        // Use tree-sitter or custom parser

        let tree = tree_sitter_mylang::parse(source)?;

        convert_tree_to_ast(tree)

    }



    fn language(&self) -> Language {

        Language::Mylang

    }

}

```

### Step 2: Add Language Enum

```rust

// crates/polyglot-frontend/src/language.rs

pub enum Language {

    // ... existing languages ...

    Mylang,

}



pub impl Language {

    pub fn tier(&self) -> LanguageTier {

        match self {

            Language::Mylang => LanguageTier::Tier4,  // or appropriate tier

            // ...

        }

    }

}

```

### Step 3: Register in Registry

```rust

// In registry.rs or similar

let mut registry = LanguageRegistry::new();

registry.register(Language::Mylang, Box::new(MyLangParser));

```

### Step 4: Add Tests

```rust

#[cfg(test)]

mod tests {

    use super::*;



    #[test]

    fn test_mylang_parse_simple() {

        let source = "x := 10;";

        let ast = MyLangParser.parse(source).unwrap();

        assert_eq!(ast.root.statements.len(), 1);

    }

}

```

### Step 5: Update Documentation

- Add to `docs/API_REFERENCE.md` (polyglot-frontend section)
- Add to README.md language support table
- Update CONTRIBUTING.md if integration is complex

---

## Adding a New Proof Integration

### Step 1: Design Adapter

```rust

// crates/proof-validator/src/adapters/myprover.rs

pub struct MyProverAdapter;



impl ProofVerifier for MyProverAdapter {

    fn verify(&self, obligation: &ProofObligation, proof: &ProofTerm) -> Result<ProofStatus> {

        // Invoke external tool (Agda, Lean, etc.)

        // Return status: Proved | Disproved | Manual | Error

    }

}

```

### Step 2: Integrate with Validator

```rust

// In proof-validator.rs

pub struct ProofValidator {

    verifiers: HashMap<String, Box<dyn ProofVerifier>>,

}



impl ProofValidator {

    pub fn add_verifier(&mut self, name: &str, verifier: Box<dyn ProofVerifier>) {

        self.verifiers.insert(name.to_string(), verifier);

    }

}

```

### Step 3: Test End-to-End

```rust

#[test]

fn test_proof_verification_with_myprover() {

    let obligation = create_test_obligation();

    let proof = invoke_myprover(&obligation)?;

    assert_eq!(proof.status, ProofStatus::Proved);

}

```

---

## Security & Audit Contributions

### Reporting Security Issues

**Do NOT open public issues for security vulnerabilities.**

Email security concerns to: **[security-contact-TBD]**

Include:
- Description of vulnerability
- Proof-of-concept (if applicable)
- Steps to reproduce
- Suggested mitigation

Vulnerability disclosure timeline:
1. Report received
2. Assessment (48 hours)
3. Fix development (1-2 weeks typical)
4. Fix release & public disclosure

### Audit Contributions

If conducting security audit, provide:
- Threat description and CWE reference
- Reproduction steps
- Severity rating (CVSS or descriptive)
- Suggested remediation
- Proof-of-concept code (if applicable)

---

## Documentation Contributions

### Fixing Docs

- Fix typos, unclear sections, broken examples
- Update outdated information
- Add clarifying examples
- Link related documentation

### Adding New Docs

- Get consensus via GitHub issue first (avoid writing docs that won't be merged)
- Include with corresponding code changes
- Follow markdown style (see docs/ for examples)
- Keep examples runnable and tested

---

## Community Guidelines

1. **Be Respectful** — All contributors and maintainers are volunteers
2. **Assume Good Intent** — Technical disagreements are not personal
3. **Focus on Code** — Critique code, not contributors
4. **Share Knowledge** — Help newer contributors learn
5. **No Tolerance for Harassment** — We enforce a Code of Conduct

---

## Questions & Support

- **General questions:** GitHub Discussions
- **Implementation questions:** GitHub Issues
- **Security questions:** Private email (see above)
- **Design feedback:** Pull request comments

---

## Recognition

Contributors are recognized in:
1. Git commit author line (Co-Authored-By)
2. GitHub contributors graph
3. Release notes (for significant contributions)
4. Project README (for sustained contributors)

---

**Thank you for contributing to ROWM!**

*"EVIDENCE OR SILENCE." — Make your contributions count.*