Skip to content

Commit df8441b

Browse files
petervartanianpetervartanian
committed
1
1 parent 02b5ba4 commit df8441b

File tree

20,106 files changed

+3060936
-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.

20,106 files changed

+3060936
-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: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# omphalOS
2+
3+
**Computational infrastructure for institutionalized doubt.**
4+
5+
[![License: CC0](https://img.shields.io/badge/License-CC0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
6+
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18344930.svg)](https://doi.org/10.5281/zenodo.18344930)
8+
9+
## What This Is
10+
11+
omphalOS surfaces patterns for review, then forces the record to carry uncertainty, rival explanations, and falsifiers as first-class structure.
12+
13+
You cannot export a packet without documenting what you don't know. Every SQL query scrolls you past epistemic warnings before you reach the data. Three years later when someone challenges your analysis, every step is reproducible bit-for-bit.
14+
15+
This is not risk scoring. This is not classification. This is hypothesis-generating pattern detection where the system makes doubt structurally unavoidable.
16+
17+
## Who Uses This
18+
19+
Intelligence analysts, export control investigators, sanctions compliance officers, trade finance investigators—anyone working in adversarial legal contexts where "the algorithm flagged it" is insufficient and analytical reasoning must survive scrutiny.
20+
21+
Application domains: export control casework (EAR, ITAR), sanctions enforcement (OFAC, multilateral regimes), trade-based money laundering, supply chain risk, proliferation finance.
22+
23+
## Quick Start
24+
25+
```bash
26+
# Clone and verify
27+
git clone https://github.com/your-org/omphalOS
28+
cd omphalOS
29+
PYTHONPATH=core/src python -m omphalos.cli pack verify packs/INDEX.json
30+
31+
# Build synthetic world and execute case
32+
PYTHONPATH=core/src python -m omphalos.cli world build --profile hydrate --out hydrate/world
33+
PYTHONPATH=core/src python -m omphalos.cli case run hydrate/cases/case_chemicals.json --out hydrate/runs
34+
35+
# Verify integrity and apply export gate
36+
PYTHONPATH=core/src python -m omphalos.cli case verify hydrate/runs/case_chemicals/<run_id>/
37+
PYTHONPATH=core/src python -m omphalos.cli export hydrate/runs/case_chemicals/<run_id>/packet.json
38+
39+
# Run conformance suite
40+
PYTHONPATH=core/src python -m omphalos.cli conformance
41+
```
42+
43+
Workbench UI: `core/ui/analyst-workbench.html` (single offline HTML file)
44+
45+
See [TUTORIAL.md](docs/TUTORIAL.md) for walkthrough.
46+
47+
## Architecture
48+
49+
Three object types:
50+
51+
- **Cases**: investigative questions, scope, selected investigations
52+
- **Runs**: portable executions producing checksummed artifacts
53+
- **Packets**: claims with mandatory doubt structure (unknowns, alternatives, falsifiers)
54+
55+
Trust is distributed across independent implementations (Python reference runtime, Rust cryptographic attestation, Go independent SQL execution). No single implementation is authoritative.
56+
57+
Offline-first: operates in air-gapped environments. All dependencies pre-packaged in cryptographically signed packs.
58+
59+
```
60+
┌───────────────────────────────────────────┐
61+
│ omphalOS │
62+
├───────────────────────────────────────────┤
63+
│ Cases → Python Runtime → SQL Warehouse │
64+
│ ↓ │
65+
│ Run Artifacts (Packets) │
66+
│ ↓ │
67+
│ ┌────────┬────────┬────────┐ │
68+
│ │ Rust │ Go │ Export │ │
69+
│ │ Verify │ Verify │ Gate │ │
70+
│ └────────┴────────┴────────┘ │
71+
└───────────────────────────────────────────┘
72+
```
73+
74+
See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for complete design.
75+
76+
## The Canon
77+
78+
Every SQL investigation contains 60+ repetitions of "interpret with restraint; prefer simpler explanations; record unknowns" before you reach the query. This is not documentation—it is infrastructure that makes epistemic humility structurally unavoidable.
79+
80+
Research shows single warnings are psychologically distant. Repeated environmental cues durably shift judgment patterns. The Canon exploits this.
81+
82+
See [CANON.md](docs/CANON.md) for philosophical foundation.
83+
84+
## Investigation Catalog
85+
86+
20,000 parametric SQL queries detecting patterns: payment fragmentation, entity clustering, temporal anomalies, cross-domain procurement, price outliers, network topology.
87+
88+
Each investigation includes Canon and Margin headers (epistemic safeguards), metadata (domain, intent, method), CTE-based SQL (reviewable), limited result sets (bounded).
89+
90+
See [INVESTIGATIONS.md](docs/INVESTIGATIONS.md) for taxonomy.
91+
92+
## Export Gate
93+
94+
Packets must contain:
95+
- Evidence (artifact pointers with cryptographic hashes)
96+
- Unknowns (what claims do not establish)
97+
- Alternatives (rival explanations)
98+
- Falsifiers (what would overturn claims)
99+
100+
No exceptions. The export gate rejects packets lacking any of these. It scans for prohibited certainty language ("proves", "must be", "conclusively"). This is enforced programmatically.
101+
102+
See [STANDARDS_OF_REVIEW.md](docs/STANDARDS_OF_REVIEW.md) for normative requirements.
103+
104+
## Conformance
105+
106+
The conformance suite gates integrity:
107+
108+
(i) Pack checksum verification
109+
(ii) Case execution producing checksummed run
110+
(iii) Manifest integrity validation
111+
(iv) Export gate evaluation (packet admissibility)
112+
(v) Polycentric verification (Rust, Go)
113+
114+
```bash
115+
PYTHONPATH=core/src python -m omphalos.cli conformance
116+
```
117+
118+
See [CONFORMANCE.md](docs/CONFORMANCE.md) for release contract.
119+
120+
## Documentation
121+
122+
| Document | Coverage |
123+
|----------|----------|
124+
| [CONFORMANCE.md](docs/CONFORMANCE.md) | Conformance suite and release contract |
125+
| [STANDARDS_OF_REVIEW.md](docs/STANDARDS_OF_REVIEW.md) | Export gate requirements (normative) |
126+
| [CANON.md](docs/CANON.md) | Epistemic humility as infrastructure |
127+
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design and polycentric verification |
128+
| [INVESTIGATIONS.md](docs/INVESTIGATIONS.md) | SQL catalog and pattern taxonomy |
129+
| [TUTORIAL.md](docs/TUTORIAL.md) | First case walkthrough |
130+
| [THREAT_MODEL.md](docs/THREAT_MODEL.md) | Security assumptions and mitigations |
131+
| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment |
132+
| [RESEARCH.md](docs/RESEARCH.md) | Academic positioning |
133+
134+
## Design Philosophy
135+
136+
Traditional algorithmic systems optimize for precision and recall, treating detection as classification. This fails when (i) base rates are exceptionally low (<0.01% of transactions), (ii) adversaries adapt through FOIA and litigation disclosure, (iii) conclusions must survive adversarial legal scrutiny.
137+
138+
omphalOS inverts this: hypothesis-generating pattern detection (not classification), transparency by design (assumes disclosure), systematic documentation of unknowns (not confident predictions).
139+
140+
Epistemic humility is architectural, not aspirational.
141+
142+
## Security and Privacy
143+
144+
**Export Control Notice**: Publicly released, not subject to EAR controls. Contains no controlled technical data. Datasets are synthetic and non-identifiable.
145+
146+
**Privacy by Design**: Packets contain aggregates, not individual transactions. Export gates block credentials and secrets. Demonstration world-states are synthetic; production deployments apply redaction protocols.
147+
148+
See [THREAT_MODEL.md](docs/THREAT_MODEL.md) and [SECURITY.md](SECURITY.md).
149+
150+
## Contributing
151+
152+
See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
153+
154+
Requirements: (i) synthetic data only, (ii) SQL investigations follow Canon/Margin conventions, (iii) code passes verification, (iv) no credentials or classified material.
155+
156+
## License
157+
158+
CC0 1.0 Universal (Public Domain)
159+
160+
U.S. Government work not subject to copyright protection domestically. Foreign copyrights may apply. To the extent possible under law, all copyright and related rights dedicated to the public domain worldwide.
161+
162+
See [LICENSE](LICENSE).
163+
164+
## Citation
165+
166+
```bibtex
167+
@software{omphalos2026,
168+
author = {{U.S. Government}},
169+
title = {omphalOS: Computational Infrastructure for Institutionalized Doubt},
170+
year = {2026},
171+
doi = {10.5281/zenodo.18344930},
172+
url = {https://github.com/your-org/omphalOS}
173+
}
174+
```
175+
176+
## Acknowledgments
177+
178+
Influenced by Richards Heuer's *Psychology of Intelligence Analysis*, Elinor Ostrom's polycentric governance theory, the CompCert verified software project.
179+
180+
The system is transparent not because it has nothing to hide, but because transparency is what makes it defensible.

0 commit comments

Comments
 (0)