A coeffect-typed programming language for a personal AI organism.
agency safety without supervision
via typed (capability, budget, fitness) coeffects + refusal-as-value
opinionated about who-decides-what
Not a product. Not a library. A bespoke instrument for one operator's JANUS
organism (NOESIS · LIS · CORTEX · PORTUNUS · JANUS). Designed against
~/projects/janus/docs/specs/.
| version | what works | gate |
|---|---|---|
| v0.1 | constitution-hash binding tool · bind/check/scan-stale standalone | end-to-end amendment workflow |
| v0.2 | Python interpreter · lex+parse+check+run · 9 smoke tests | hello.numen runs |
| v0.3 | 10 effect primitives (fs · kg · llm · time) · Refused short-circuit | dream_test.numen against live Ollama |
| v0.4 | pattern matching · sum types · constructors · Allowed/Refused destructuring | ctor_demo.numen prints 6 lines correctly |
| v0.5 | REPL · minimal-safe formatter · caret-pointer diagnostics | numen repl interactive · 17 tests |
| v0.6 | time-typed values · Datetime/Date/Duration · arithmetic | time_demo.numen pattern-matches Datetime |
| v0.7 | refusal chaining · stdlib (or_else · is_refused · reason_of · rule_of) | propagation chain visible in stderr · 22 tests |
| v0.8 | dream-loop runner in numen · systemd nightly timer · 4 phases | run_nightly.sh produces dated artifacts |
| v0.9 | organism-write primitives · noesis_append · autobiography_append · phase_commit (WAL) | sqlite row + .committed/ on disk · ADR-004 honored |
22/22 smoke tests passing. Every feature has a runnable example + test.
cd ~/projects/numen
# Run a numen program against the live constitution
~/noesis/.venv/bin/python -m numen.interp.cli run numen/examples/hello.numen
# Interactive REPL
~/noesis/.venv/bin/python -m numen.interp.cli repl
# Run a real dream-cycle (writes to ~/.janus/dream/{today}/)
~/.janus/dream/run_nightly.sh
# Run all 22 smoke tests
~/noesis/.venv/bin/python -m numen.tests.test_smoke
# Format a source file
~/noesis/.venv/bin/python -m numen.interp.cli fmt numen/examples/dream_loop.numen
# Verify constitution hashes are all current
~/noesis/.venv/bin/python numen/tools/constitution_check.py \
--constitution ~/.janus/constitution.toml checkEvery effectful numen function declares a triple:
fn commit_dream_phase(date: String, phase: String, content: String) -> String
needs fs.write & kg.write -- capability
costs gpu_seconds <= 10 -- budget
satisfies Art.4_dream_loop_sole_writer @ "1f7f2701" -- fitness
satisfies Art.16_dream_phase_atomicity @ "0462b5f2"
{
...
}
- capability: a set on a subtyping lattice (fs.read ⊂ fs ⊂ io). A function can only call other functions whose required caps are in the caller's set (with descendants).
- budget: an additive grade per economy meter (cloud_tokens · gpu_seconds · attention_grants). Callee budgets sum into the caller; the compiler refuses if the sum exceeds the caller's declared bound.
- fitness: a set of constitutional article IDs with hash-bound content. When the operator amends an article, every function carrying the old hash is flagged for review.
Refusal is a first-class value:
let result = llm_local("model", "prompt", 96);
match result {
Allowed(s) => print(s),
Refused(r) => print(concat("model declined: ", reason_of(result)))
}
~/projects/numen/
├── README.md (this file)
├── ARCHITECTURE.md (living architecture book · LEDGER · doctrine)
├── docs/
│ └── architecture.html (broadsheet rendering · v0.3.1)
├── bootstrap.sh (single-shot install for fresh operators)
├── numen/
│ ├── interp/
│ │ ├── tokens.py · lexer.py · ast.py · parser.py
│ │ ├── coeffects.py (lattice · semiring · set)
│ │ ├── checker.py (live constitution validation + subsumption)
│ │ ├── runtime.py (tree-walking · runtime gate · pattern matching · refusal chain)
│ │ ├── prims.py (24 primitives: fs · kg · llm · time · introspection · organism-write)
│ │ ├── time_values.py (Datetime · Date · Duration arithmetic)
│ │ ├── repl.py (interactive · multi-line · :meta commands)
│ │ ├── fmt.py (minimal-safe formatter)
│ │ ├── diagnostics.py (caret-pointer parse errors)
│ │ └── cli.py (numen lex|parse|check|run|fmt|repl)
│ ├── tools/
│ │ └── constitution_check.py (bind/check/scan-stale)
│ ├── examples/
│ │ ├── hello.numen
│ │ ├── dream_demo.numen (v0.2 · multi-fn coeffect composition)
│ │ ├── refusal_demo.numen (v0.2 · adversarial · caller missing cap)
│ │ ├── dream_test.numen (v0.3 · live Ollama)
│ │ ├── morning_brief.numen (v0.3 · NOESIS-grounded)
│ │ ├── match_lit.numen (v0.4 · int literal patterns)
│ │ ├── match_demo.numen (v0.4 · Allowed/Refused destructure)
│ │ ├── ctor_demo.numen (v0.4 · user sum types)
│ │ ├── time_demo.numen (v0.6 · time-typed values)
│ │ ├── refusal_chain.numen (v0.7 · or_else + introspection)
│ │ ├── dream_loop.numen (v0.8 · nightly dream-loop · 4 phases)
│ │ └── dream_v09.numen (v0.9 · WAL discipline · staging + autobiography)
│ └── tests/
│ └── test_smoke.py (22 tests · 22/22 passing)
└── granule-upstream/ (cloned · deferred build per v0.1 README)
~/.janus/
├── constitution.toml (5 ratified articles · hash-bound)
├── dream/
│ ├── run_nightly.sh (the v0.8 dream-loop launcher)
│ └── {YYYY-MM-DD}/ (dated phase artifacts + WAL)
│ ├── P1-morning-brief.md · P3-morning-brief.md · P4-... · P7-...
│ ├── P1.committed/output.md · P3.committed/output.md (v0.9 WAL)
│ ├── wal.jsonl (v0.9 per-phase WAL trace)
│ └── run.log
├── staging/
│ └── {workspace}-{date}.jsonl (v0.9 staging writes via noesis_append)
└── state.db (v0.9 sqlite · autobiography table)
~/.config/systemd/user/
├── numen-dream.service (v0.8 oneshot · 20G memory cap)
└── numen-dream.timer (v0.8 · 02:00 nightly · persistent)
v0.9 ships. 9 versions in one session. ~70% confident the design survives to v1.0.
The constitution-coupling protocol — the genuinely novel piece per ORACLE 2026-05-16 — works end-to-end. Every numen function bound to article content via BLAKE3-8 hash, validated live at every check. Refusal as first-class value. WAL-disciplined dream-cycle producing real artifacts nightly. The doctrine made real.
What remains for v1.0 final: self-host pass 1 (numen parser written in numen, typechecks itself). That's the v0.7 INSANE PLAN gate. v1.0 ships when that gate clears.
ARCHITECTURE.md— the living architecture book (newspaper-style, two registers)docs/architecture.html— broadsheet rendering (v0.3.1)~/projects/janus/docs/specs/foundations/2026-05-16-numen-language-v0.md— the v0 design spec- Hack coeffect doc at
~/repos/pl-corpus/research-prototypes/hhvm-hack/hphp/hack/doc/vision_docs/tracking_effects_and_coeffects.md— production-tested analog
Co-authored under the JANUS architecture · per ADRs 001-006 · NOESIS-grounded · ORACLE-validated.