Skip to content

Commit 95fd4ec

Browse files
petervartanianpetervartanian
committed
1
1 parent abc396e commit 95fd4ec

File tree

14,004 files changed

+2139590
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

14,004 files changed

+2139590
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Contributing to omphalOS
2+
3+
Thank you for your interest in contributing to omphalOS. This document outlines how to contribute code, investigations, documentation, and bug reports.
4+
5+
## Code of Conduct
6+
7+
Be professional, respectful, and constructive. This is a tool for serious analytical work—maintain that standard in all interactions.
8+
9+
## How to Contribute
10+
11+
### 1. Bug Reports
12+
13+
Use GitHub Issues to report bugs. Include:
14+
- What you did (exact commands, case definitions)
15+
- What you expected
16+
- What actually happened
17+
- System information (OS, Python version, omphalOS commit SHA)
18+
19+
### 2. Investigation Contributions
20+
21+
Have a novel pattern for detecting evasion/proliferation? Contribute it:
22+
23+
**Steps**:
24+
1. Write SQL investigation following catalog conventions (Canon/Margin headers, CTE structure, LIMIT clause)
25+
2. Place in `core/sql/investigations/custom/custom_<initials>_<date>_<description>.sql`
26+
3. Create test case with synthetic data showing the pattern
27+
4. Document false positive scenarios
28+
5. Submit pull request with investigation + test + docs
29+
30+
**Example**:
31+
```sql
32+
-- Investigation: custom_jd_20260123_circular_flows
33+
-- Domain: all
34+
-- Intent: Detect circular shipment patterns (A→B→A)
35+
-- [Canon 01-60 + Margin 001-045]
36+
WITH ...
37+
```
38+
39+
### 3. Documentation Improvements
40+
41+
Found unclear docs? Submit PR with improvements. Follow existing tone (technical but accessible).
42+
43+
### 4. Code Contributions
44+
45+
**Before coding**:
46+
- Open an issue describing what you want to build
47+
- Discuss approach with maintainers
48+
- Get approval before significant work
49+
50+
**Code standards**:
51+
- Python: Follow PEP 8, use `black` formatter
52+
- Rust: Use `rustfmt`
53+
- Go: Use `gofmt`
54+
- All code must include docstrings/comments
55+
- No external dependencies without approval (offline-first requirement)
56+
57+
**Testing**:
58+
- All new investigations must have test cases
59+
- All code changes must not break existing tests
60+
- Run `pytest` before submitting
61+
62+
### 5. Security Contributions
63+
64+
Found a vulnerability? See SECURITY.md for responsible disclosure process.
65+
66+
**Do NOT** open public issues for security vulnerabilities.
67+
68+
## Contribution Requirements
69+
70+
### What You Can Submit
71+
72+
✅ **Allowed**:
73+
- SQL investigations using synthetic data
74+
- Documentation improvements
75+
- Bug fixes
76+
- Performance optimizations
77+
- New verifiers (additional languages)
78+
- UI enhancements
79+
- Test cases
80+
81+
❌ **Prohibited**:
82+
- Real trade data, PII, BCI, or classified information
83+
- Credentials, API keys, or secrets (even fake ones that look real)
84+
- Copyrighted material without attribution
85+
- Malicious code or backdoors
86+
87+
### Data Requirements
88+
89+
**CRITICAL**: All contributed data must be **synthetic and non-identifiable**.
90+
91+
- Do NOT include real company names, addresses, or transaction records
92+
- Do NOT include data derived from classified sources
93+
- Do NOT include proprietary data from commercial providers
94+
95+
When in doubt, generate synthetic test data using omphalOS's world builder.
96+
97+
## Pull Request Process
98+
99+
1. **Fork** the repository
100+
2. **Create branch**: `git checkout -b feature/your-feature-name`
101+
3. **Make changes**: Follow code standards above
102+
4. **Test**: Ensure `pytest` passes, run verification on sample cases
103+
5. **Commit**: Use clear commit messages explaining *why*, not just *what*
104+
6. **Push**: `git push origin feature/your-feature-name`
105+
7. **Open PR**: Describe changes, link to related issues, explain testing performed
106+
107+
**PR Requirements**:
108+
- Passes all CI checks (linting, tests, pack verification)
109+
- Includes documentation updates if changing user-facing behavior
110+
- Includes test cases for new functionality
111+
- No merge conflicts with `main`
112+
113+
## Review Process
114+
115+
Maintainers will review within 7 days. Expect:
116+
- Questions about design choices
117+
- Requests for additional tests or documentation
118+
- Style/formatting feedback
119+
120+
**Be patient**. This is a system used for national security work—thoroughness matters more than speed.
121+
122+
## License
123+
124+
By contributing, you agree that your contributions will be licensed under CC0 (public domain). You affirm that:
125+
- You have the right to submit the contribution
126+
- The contribution is your original work or properly attributed
127+
- The contribution contains no classified, proprietary, or sensitive information
128+
129+
## Recognition
130+
131+
Contributors will be acknowledged in:
132+
- `CONTRIBUTORS.md` file (if substantial contribution)
133+
- Release notes for version where contribution appears
134+
- Academic publications citing omphalOS (if contribution is methodologically significant)
135+
136+
## Questions?
137+
138+
Open a GitHub Discussion (not an Issue) for:
139+
- How to implement a feature
140+
- Design questions
141+
- General usage questions
142+
143+
Use Issues only for bugs and concrete feature requests.
144+
145+
---
146+
147+
**Thank you for helping make intelligence analysis more transparent, reproducible, and defensible.**

‎LICENSE‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
CC0 1.0 Universal
2+
3+
Statement of Purpose
4+
5+
The laws of most jurisdictions throughout the world automatically confer
6+
exclusive Copyright and Related Rights (defined below) upon the creator and
7+
subsequent owner(s) (each and all, an "owner") of an original work of
8+
authorship and/or a database (each, a "Work").
9+
10+
Certain owners wish to permanently relinquish those rights to a Work for the
11+
purpose of contributing to a commons of creative, cultural and scientific
12+
works ("Commons") that the public can reliably and without fear of later
13+
claims of infringement build upon, modify, incorporate in other works, reuse
14+
and redistribute as freely as possible in any form whatsoever and for any
15+
purposes, including without limitation commercial purposes. These owners may
16+
contribute to the Commons to promote the ideal of a free culture and the
17+
further production of creative, cultural and scientific works, or to gain
18+
reputation or greater distribution for their Work in part through the use and
19+
efforts of others.
20+
21+
For these and/or other purposes and motivations, and without any expectation
22+
of additional consideration or compensation, the person associating CC0 with a
23+
Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
24+
and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
25+
and publicly distribute the Work under its terms, with knowledge of his or her
26+
Copyright and Related Rights in the Work and the meaning and intended legal
27+
effect of CC0 on those rights.
28+
29+
This work was produced by the United States Government and is not subject to
30+
copyright protection in the United States. Foreign copyrights may apply.

‎README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# omphalOS
2+
3+
**A polycentric, offline-capable casework suite for export control and sanctions analysis.**
4+
5+
omphalOS is built as computational infrastructure for *institutionalized doubt*: it surfaces patterns for review, then forces the record to carry uncertainty, rival explanations, and falsifiers as first-class structure.
6+
7+
## What v1.0 means
8+
9+
Version 1.0 is a contract:
10+
11+
- case, packet, and run-manifest schemas are frozen under `core/schemas/`
12+
- every run is portable: it snapshots the case and the packs it used
13+
- every artifact is checksummed; the manifest is computed last
14+
- the export gate refuses packets that lack mandatory epistemic scaffolding
15+
16+
See `docs/CONFORMANCE.md` and `docs/STANDARDS_OF_REVIEW.md`.
17+
18+
## Quick start
19+
20+
```bash
21+
# Verify offline packs
22+
PYTHONPATH=core/src python -m omphalos.cli pack verify packs/INDEX.json
23+
24+
# Run a case (portable run directory under hydrate/runs)
25+
PYTHONPATH=core/src python -m omphalos.cli case run hydrate/cases/case_chemicals.json --out hydrate/runs
26+
27+
# Verify integrity and apply the export gate
28+
PYTHONPATH=core/src python -m omphalos.cli case verify hydrate/runs/case_chemicals/<run_id>/
29+
PYTHONPATH=core/src python -m omphalos.cli export hydrate/runs/case_chemicals/<run_id>/packet.json
30+
31+
# Run the release constitution
32+
PYTHONPATH=core/src python -m omphalos.cli conformance
33+
```
34+
35+
The workbench UI is a single offline HTML file at `core/ui/analyst-workbench.html`.
36+
37+
## Architecture (high level)
38+
39+
omphalOS operates through three object types:
40+
41+
- **Cases**: investigative questions, scope, and selected investigations
42+
- **Runs**: portable materializations of a case against a world slice, producing checksummed artifacts
43+
- **Packets**: claims plus provenance, and mandatory doubt structure (unknowns, alternatives, falsifiers)
44+
45+
The system’s posture is intentionally non-classificatory: it does not assign risk scores, predict behavior, or operate as real-time monitoring.
46+
47+
## Investigation catalog
48+
49+
The shipped SQL catalog contains **20,000** reviewable investigations. Each is a single query, CTE-based, and bounded by a terminal `LIMIT`. Each includes Canon and Margin reminders designed to make interpretive restraint procedurally non-optional.
50+
51+
See `docs/INVESTIGATIONS.md` and `docs/CANON.md`.
52+
53+
## Polycentric verification
54+
55+
The reference runtime is Python. Independent verifiers in Go and Rust perform integrity checks and packet admissibility checks. Where toolchains are provisioned offline, conformance attempts to execute them as independent witnesses.
56+
57+
See `docs/CONFORMANCE.md`.
58+
59+
## License
60+
61+
CC0 1.0 Universal (Public Domain). See `LICENSE`.

‎RUNBOOK.txt‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
RUNBOOK
2+
3+
Verify packs:
4+
PYTHONPATH=core/src python -m omphalos.cli pack verify packs/INDEX.json
5+
6+
Inspect hydrated content:
7+
hydrate/world/meta.json
8+
hydrate/cases/case_chemicals.json
9+
hydrate/runs/case_chemicals/<run_id>/
10+
11+
Run again:
12+
PYTHONPATH=core/src python -m omphalos.cli case run hydrate/cases/case_chemicals.json --out hydrate/runs
13+
14+
Verify a run:
15+
PYTHONPATH=core/src python -m omphalos.cli case verify hydrate/runs/case_chemicals/<run_id>/
16+
17+
Export gate:
18+
PYTHONPATH=core/src python -m omphalos.cli export hydrate/runs/case_chemicals/<run_id>/packet.json

0 commit comments

Comments
 (0)