I build the contract layer for AI execution.
Most AI systems today have no contracts. A prompt goes in, something comes out, and the entire downstream pipeline hopes the shape is right. When it isn't β and it will be β the system retries, falls back, or silently degrades. There is no compile step. No type check. No guarantee. Just strings, probability, and prayer.
I think this is the central unsolved problem of production AI: not intelligence, but reliability. We have models that can reason, generate, and plan β but we have almost no infrastructure to ensure they do it the same way twice, in the same format, within the same resource bounds, with the same failure semantics.
This is the gap I work in.
FACET is a formal specification and compiler toolchain that treats AI behavior as compiled software. You define contracts β typed inputs, constrained outputs, explicit failure modes β and the compiler enforces them before the model ever runs. If the output doesn't match the contract, it's rejected. Not logged. Not retried. Rejected. The guarantee is structural, not statistical.
IOSM is the engineering methodology that sits alongside it: a reproducible improvement cycle with strict phases, quality gates, and canonical metrics. It answers a different question β not "does the system work?" but "is the system getting better, and can I prove it?"
Think of it as what TypeScript did for JavaScript, but applied to AI execution. TypeScript didn't make JavaScript smarter β it made JavaScript accountable. FACET does the same for LLMs.
Two ecosystems. One thesis: AI systems should be engineered, not improvised.
The problem: LLM returns {status: "ok"} instead of {status: "success"}. Your payment service receives invalid data. Transaction state is unknown. Retry? Refund? Hope?
With FACET: @output status: enum["success","failed"] β enforced at compile time. If the output doesn't match the schema, the run is rejected before it reaches your service. Not retried. Rejected.
The problem: refactor "feels done". No baseline. No metrics. No evidence it actually got better. Ship and hope.
With IOSM: baseline snapshot β hypothesis β 4 gated phases β cycle report. Simplicity went from 0.51 β 0.65. Modularity 0.47 β 0.56. Not opinions β measurements.
The problem: 8 agents run in parallel. 3 write to the same file. Outputs drift between runs. No rollback. No coordination. Chaos.
With Swarm-IOSM: file-level locks prevent conflicts. Quality gates reject substandard work. Auto-spawn fills capability gaps. Every agent operates within a contract β deterministic dispatch, not improvisation.
The problem: you switch between 5 different AI tools. Each has its own context, its own memory, its own interface. Nothing connects. You are the integration layer.
With IOSM-CLI: one terminal, 507 models across 15+ providers, MCP tool integration, project memory, session checkpoints, built-in skills. A single runtime that understands your codebase β not a chat window with autocomplete.
The normative specification for deterministic, compiled AI execution.
The Architectural Priority
Engineers rush to use runtimes and orchestrators (swarm-iosm,iosm-cli), but tools are ephemeral. The Standard is the permanent foundation. Without a strict contract layer, multi-agent orchestration is just parallel chaos. This repository is the source of truth for the entire ecosystem. Read the standard first.
FACET is not another framework or wrapper. It is a formal contract layer that treats AI behavior as compiled software, not probabilistic improvisation.
The standard defines a Neural Architecture Description Language (NADL) with typed inputs, constrained outputs, deterministic variable evaluation (R-DAG), explicit token budget allocation (Token Box Model), and fail-closed runtime guards. Every contract compiles to Canonical JSON β a stable, diffable, cacheable intermediate representation that is identical regardless of which model, provider, or runtime executes it.
@system
role: "payment-processor"
@input amount: float(min=0.01)
@input currency: enum["USD","EUR","GBP"]
@output status: enum["success","failed"]
@output tx_id: string(min_length=8)
@policy
max_tokens: 512
on_invalid_output: reject
β facet-fct build payment.facet β
{
"meta": { "version": "2.1.3", "hash": "a7f3c9..." },
"inputs": { "amount": { "type": "float", "min": 0.01 }, "currency": { "type": "enum", "values": ["USD","EUR","GBP"] } },
"outputs": { "status": { "type": "enum", "values": ["success","failed"] }, "tx_id": { "type": "string", "min_length": 8 } },
"policy": { "max_tokens": 512, "on_invalid_output": "reject" }
}Invalid output never reaches your service. The contract is enforced before generation, not after. Same inputs β same canonical JSON β same guarantees. Always.
- Typed contracts β inputs and outputs are schema-enforced at compile time
- Canonical JSON IR β deterministic, stable-hashed, provider-independent
- R-DAG evaluation β variable dependencies resolved in guaranteed topological order
- Token Box Model β explicit budget allocation with compression/drop rules
- Fail-closed guards β invalid output is rejected, not logged and forwarded
- 4 strict phases β Improve β Optimize β Shrink β Modularize
- Quality gates β each phase must pass before the next begins
- 6 canonical metrics β complexity, simplicity, modularity, coverage, debt, performance
- IOSM-Index β single aggregate score that tracks system health over time
- Reproducible cycles β every improvement is baselined, hypothesized, measured, and reported
FACET Standard
Normative Specification
v2.1.3 Β· REC-PROD
NADL Β· FTS Β· R-DAG Β· Token Box
Policy Β· Guards Β· Conformance
facet-compiler
Reference Implementation
Rust Β· fct 0.1.2 Β· 6 crates
AST β FTS β R-DAG β Canonical JSON
Other impls must match its behavior
IOSM Specification
Engineering Methodology
v1.0 Β· JSON schemas Β· Validator
4 phases Β· 6 metrics Β· Quality gates
Reproducible improvement cycles
FACET MCP
Execution Boundary
SIMD Γγ°γ€ Β· WebSocket Β· 70 tests
execute Β· lenses Β· validate
Protocol adapter & host
Most AI CLIs are optimized for conversation.
IOSM CLI is optimized for controlled engineering execution β working directly against your filesystem and shell, orchestrating agents, tracking metrics, and running improvement cycles that can be audited, repeated, and benchmarked.
IOSM CLI is a terminal-native AI engineering runtime built for engineers who need more than a chat window. It connects to 507 models across 15+ providers, but that's not the point. The point is what happens after the model responds: contracts enforce scope, orchestration splits complex work across parallel agents with file-level locking, quality gates reject substandard output, and every change is checkpointed so you can roll back anything. It ships with the IOSM methodology built in β the same 4-phase cycle, 6 metrics, and quality gates that the specification defines, executable directly from your terminal against your actual codebase.
| Command | What it does |
|---|---|
/contract |
Engineering contract editor β scope, constraints, quality gates, Definition of Done |
/singular |
Feature feasibility: baseline scan β agent analysis β 3 implementation options with trade-offs |
/swarm |
Multi-agent orchestration: run, watch, retry, resume β file locks and quality gates |
/ultrathink |
Deep multi-iteration read-only analysis with self-check checkpoints β up to 12 passes |
/orchestrate |
Manual multi-agent delegation with parallel execution, profile assignment, shared memory |
/iosm |
Full IOSM improvement cycle targeting a specific Index score β plan β status β report |
/checkpoint |
Save named rollback points. /rollback restores instantly. Filesystem-level undo |
/semantic |
Semantic search β setup, auto-index, query across entire codebase with embeddings |
/memory |
Persistent project notes that survive session boundaries β context that never disappears |
/bg |
Background process manager β run dev servers, watchers, long tasks with list, logs, stop |
| 4 Profiles | 7 Integration Modes | 66 Extension Examples | Policy Engine v2 |
|---|---|---|---|
full Β· plan Β· meta Β· iosm |
TUI Β· Print Β· JSON stream | Tools Β· Hooks Β· UI Β· Commands | Layered permissions Β· Trust ledger |
| + specialist subagent profiles | JSON-RPC Β· Telegram Β· CI Β· SDK | + 12 SDK examples | Per-tool decisions Β· Sandbox |
Controlled execution workflow:
/contract β Define scope, constraints, quality gates, DoD
/singular "Refactor auth" β Baseline scan β 3 options with trade-offs
/swarm run --max-parallel 3 β Scopes β Locks β Gates β Checkpoints β Done
/swarm watch β Live status: tasks, budget, ETA, critical path
/iosm 0.95 --max-iterations 5 β Run IOSM cycle targeting Index β₯ 0.95
npm install -g iosm-cli # or: npx iosm-cli iosm # interactive TUI β 507 models ready iosm -p "Audit src/" # one-shot, no TUI iosm --profile plan # read-only code review iosm --mode telegram # remote control via Telegram iosm @src/main.ts -p "Explain" # pre-load files as context
FACET is not a collection of disconnected tools. It is a vertically integrated architecture.
Each project occupies a strict architectural boundary and exists to fulfill a single responsibility.
Defines the boundaries
The formal rules, language primitives, and methodologies. Provider-agnostic.
β’ facet-standard
β’ IOSM
β’ soul.md
β’ rift-spec
Enforces the rules
The toolchains that parse contracts, resolve DAGs, and emit Canonical JSON.
β’ facet-compiler Rust
β’ FACET Language Python
β’ FACET MCP Server SIMD
Executes & scales
The execution engines that orchestrate agents and enforce output structure.
β’ iosm-cli Terminal
β’ swarm-iosm Parallel
β’ rmcp-protocol Remote
Validates the standard
Constrained consumers that guarantee the contract layer holds under pressure.
β’ FACET-AGENTS Testbed
β’ FACET-FSSG Byte-stable
β’ astrovisor-mcp App
β’ enigmo Cryptography
A Self-Correcting Ecosystem
The layers police each other. If FACET-AGENTS acts non-deterministically, the Specification has a structural gap. If FACET-FSSG cannot generate a stable static site from a contract, the Compiler's intermediate representation is flawed. If swarm-iosm must bypass a quality gate to finish a task, the Methodology is incomplete.
Every repository is an assertion that the standard works.
swarm-iosm
Parallel Orchestration
Python Β· v2.1 Β· Claude Code
Locks Β· Gates Β· Auto-spawn
Scaling layer
rmcp-protocol
Distributed Coordination
FastAPI Β· Facet Engine
Three-stage funnel Β· 89% coverage
Protocol & scheduling
FACET-AGENTS
Conformance Testbed
15 specialists Β· Self-evolving
Orchestrator v2.1 Β· Γγ°γ€ faster
Validates the standard
FACET-FSSG
Canonical JSON Consumer
Static Site Generator
Canonical JSON β byte-stable HTML
Proves the IR works
I work at the boundary where formal language design, compiler construction, and distributed AI orchestration meet.
Rust TypeScript Python SIMD
Parser design (lexer β AST β IR β codegen), static analysis, deterministic execution limits, and byte-stable intermediate representations.
MCP Agents Orchestration Runtimes
Multi-provider LLM routing, context injection, semantic search, parallel subagent orchestration, and filesystem-level execution locks.
NADL RMCP Contracts RFCs
Neural Architecture Description Language design, capability-based protocols, deterministic schemas, and contract-first DDD.
IOSM Metrics CI/CD Kubernetes
Algorithmic quality gates, metric-driven phased refactoring, reproducible delivery cycles, and automated AI conformance testbeds.
soul.md
Portable spec for AI agent personas
Provider-agnostic Β· MD/YAML
astrovisor-mcp
50 astrology tools via MCP
Claude Desktop Β· TypeScript
enigmo
E2EE messaging platform
Ed25519/X25519 Β· Dart Β· Zero-knowledge
rift-spec
Next-gen UDP transport protocol
Mobile-first Β· Noise crypto