"You can't build reliable systems on top of nondeterministic contracts."
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 With FACET: |
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.
|
|
FACET Standard v2.1.3 · REC-PROD |
facet-compiler Rust · fct 0.1.2 · 6 crates |
IOSM Specification v1.0 · JSON schemas · Validator |
FACET MCP SIMD 3.7× · WebSocket · 70 tests |
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 contextFACET 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. • |
Enforces the rules The toolchains that parse contracts, resolve DAGs, and emit Canonical JSON. • |
Executes & scales The execution engines that orchestrate agents and enforce output structure. • |
Validates the standard Constrained consumers that guarantee the contract layer holds under pressure. • |
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 Python · v2.1 · Claude Code |
rmcp-protocol 
FastAPI · Facet Engine |
FACET-AGENTS 
15 specialists · Self-evolving |
FACET-FSSG Static Site Generator |
I work at the boundary where formal language design, compiler construction, and distributed AI orchestration meet.
|
Parser design (lexer → AST → IR → codegen), static analysis, deterministic execution limits, and byte-stable intermediate representations. |
Multi-provider LLM routing, context injection, semantic search, parallel subagent orchestration, and filesystem-level execution locks. |
|
Neural Architecture Description Language design, capability-based protocols, deterministic schemas, and contract-first DDD. |
Algorithmic quality gates, metric-driven phased refactoring, reproducible delivery cycles, and automated AI conformance testbeds. |
soul.md |
astrovisor-mcp |
enigmo |
rift-spec |