FACET Compiler (facet-fct)

Deterministic compiler and execution layer for FACET v2.1.3.

facet-fct compiles .facet contracts into canonical, policy-aware AI request context with explicit failure semantics (F* codes), deterministic ordering, and bounded execution behavior.

What You Get

• Deterministic pipeline: normalization -> resolution -> type check -> compute -> layout -> render
• Strict type and placement checks (FTS)
• Policy and guard fail-closed behavior (F454, F455)
• Canonical JSON output + stable document and policy hashes
• Spec-oriented examples and conformance suites in CI

Install in One Command (Recommended)

cargo install --git https://github.com/rokoss21/facet-compiler --bin facet-fct
facet-fct --version

Optional short alias:

alias fct=facet-fct

Quick Start (2 Minutes)

1) Ensure compiler is installed

facet-fct --version
# fct 0.1.2

2) Create a minimal contract

@meta
  name: "hello"

@context
  budget: 32000

@vars
  query: @input(type="string")

@system
  content: "You are a helpful assistant."

@user
  content: $query

Save as hello.facet and create runtime input:

{ "query": "Hello FACET" }

Save as hello.input.json.

3) Validate and run

facet-fct build --input hello.facet
facet-fct run --input hello.facet --runtime-input hello.input.json --exec --format pretty

Installation

Option A: Fast install from Git (Cargo)

cargo install --git https://github.com/rokoss21/facet-compiler --bin facet-fct
facet-fct --version

Option B: Download release binary

From Releases:

• Linux: facet-fct-linux-x86_64.tar.gz
• macOS (Intel): facet-fct-macos-x86_64.tar.gz
• Windows: facet-fct-windows-x86_64.zip

Example (Linux/macOS):

tar -xzf facet-fct-*.tar.gz
chmod +x facet-fct
./facet-fct --version

Option C: Build from source (compile locally)

git clone https://github.com/rokoss21/facet-compiler
cd facet-compiler
cargo build --release --bin facet-fct
./target/release/facet-fct --version

Option D: Install from local source with Cargo

cargo install --path . --bin facet-fct
facet-fct --version

Homebrew

Official Homebrew formula is not published yet. Use cargo install or release binaries.

CLI Cheatsheet

# Parse + resolve + type check
facet-fct build --input file.facet

# Full execution (default mode: --exec)
facet-fct run --input file.facet --exec
facet-fct run --input file.facet --pure

# Provide runtime @input values
facet-fct run --input file.facet --runtime-input input.json --exec

# Run @test blocks
facet-fct test --input file.facet --exec

# Dump internals
facet-fct inspect --input file.facet \
  --ast ast.json --dag dag.json --layout layout.json --policy policy.json

# Help
facet-fct --help
facet-fct run --help

Docs Map

• Documentation portal: rokoss21.github.io/facet-compiler
• Quick Start: docs/01-quickstart.md
• Execution Model: docs/15-execution-model.md
• Production Failure Scenario: docs/16-production-scenario.md
• Integration Guide: docs/18-integration-guide.md
• Spec-conformance checklist: docs/14-v2.1.3-migration-checklist.md
• Language specification: FACET-v2.1.3-Production-Language-Specification.md

Common Workflows

Validate contracts in CI

facet-fct build --input examples/spec/01_minimal.facet

Run deterministic example suites

./scripts/smoke_examples_spec.sh ./target/release/facet-fct
./scripts/spec_matrix_examples.sh ./target/release/facet-fct

Local quality gate

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test -q --workspace

Integration Pattern (Brownfield)

Minimal-risk adoption path:

1. Keep your current provider SDK and business logic.
2. Replace prompt assembly with facet-fct run.
3. Keep strict response schema validation in host code.
4. Add bounded retry/fallback policy in host runtime.

Detailed guide: docs/18-integration-guide.md

Project Scope

FACET does guarantee deterministic contract compilation/execution boundaries.

FACET does not guarantee deterministic model generation output or correctness of external APIs.

Repository Structure

• src/commands/* - CLI commands (build, run, test, inspect, codegen)
• crates/fct-parser - parser and normalization
• crates/fct-resolver - import resolution and deterministic merge
• crates/fct-validator - type/semantic/policy checks
• crates/fct-engine - compute/layout and guard-aware runtime behavior
• crates/fct-render - canonical JSON and provenance output
• crates/fct-std - standard lens registry
• docs/ - documentation and conformance evidence
• examples/spec/ - ordered specification scenarios

Ecosystem

• FACET Standard: github.com/rokoss21/facet-standard
• IOSM Methodology: github.com/rokoss21/IOSM
• IOSM CLI: github.com/rokoss21/iosm-cli

Contributing

• Contribution guide: CONTRIBUTING.md
• Issues: github.com/rokoss21/facet-compiler/issues

Author

Emil Rokossovskiy

• GitHub: github.com/rokoss21
• Email: ecsiar@gmail.com
• Site: facetcore.dev

License

Dual-licensed under MIT or Apache-2.0.