# Manifest Language Implementation

**Manifest** is a formal domain modeling language with a reference runtime implementation. It enables AI agents and developers to define business logic, data models, and behavioral constraints in a declarative, executable format.

## What Manifest Is

Manifest is a **language for expressing domain models** with:

- **Entities** with typed properties, computed values, and relationships
- **Commands** that mutate state, enforce guards, and emit events
- **Policies** for authorization and access control
- **Events** for outbox patterns and real-time communication
- **Stores** for persistence (memory, localStorage, and adapters for databases)

The language compiles to an **Intermediate Representation (IR)** that serves as the canonical contract between the compiler and runtime. The runtime executes commands deterministically, enforcing guards and policies in strict order.

## Installation

```bash
pnpm install @angriff36/manifest
# or: pnpm add @angriff36/manifest
```

This installs the runtime/compiler library plus three CLIs: `manifest` (compile,
validate, scan, projections), `manifest-mcp` (MCP server), and `manifest-lsp`
(language server).

```ts
import { compileToIR } from '@angriff36/manifest/ir-compiler';
import { RuntimeEngine } from '@angriff36/manifest';

// .manifest source → IR (the canonical contract). compileToIR is async.
const { ir, diagnostics } = await compileToIR(source);
if (!ir || diagnostics.some((d) => d.severity === 'error')) {
  throw new Error(diagnostics.map((d) => d.message).join('; '));
}

// Execute commands deterministically against the IR.
const engine = new RuntimeEngine(ir);
const result = await engine.runCommand('commandName', {/* input */});
```

```bash
npx manifest compile model.manifest      # source → IR
npx manifest validate model.manifest     # diagnostics only
```

See [exports in `package.json`](package.json) for the full subpath list
(`/compiler`, `/projections/nextjs`, `/projections/prisma`, `/audit`, `/outbox`, …).

## Key Capabilities

### ✅ Implemented

- **Full Language Parser & Compiler**: Parses Manifest source code and compiles to IR v1
- **Reference Runtime Engine**: Executes commands with policy checks, guard evaluation, and event emission
- **Conformance Test Suite**: Executable semantics via fixtures plus unit/projection/CLI tests (run `pnpm test` for current count)
- **Projections System**: Generate platform-specific code from IR. Next.js projection ships 5 surfaces (route, command, **dispatcher**, types, client) — the canonical dispatcher at `/api/manifest/[entity]/commands/[command]` is the recommended write path. Additional projections: **Prisma**, **Drizzle**, **OpenAPI 3.1**, **GraphQL** (SDL + resolver stubs), **Zod**, **TanStack Query** hooks, **JSON Schema**, **Express** and **Hono** route handlers, **Mermaid** ER/diagram export, and **LLM context** export
- **Audit Sink + Outbox Store adapters**: First-party `MemoryAuditSink` / `MemoryOutboxStore` for tests and local development; `PostgresAuditSink` / `PostgresOutboxStore` for durable production use (SQL schemas ship with the package). Runtime emits exactly one audit record per `runCommand` attempt and enqueues outbox entries on emit. See `docs/spec/adapters.md`.
- **Governance audit CLI**: `manifest audit-governance` runs five detectors (direct-writes, event-fabrication, route-drift, missing-tests, bypass-violations); `manifest integration-check` is the umbrella validator for downstream consumers
- **Runtime UI**: Interactive development environment for testing Manifest programs
- **Event Logging**: Persistent event log with payload inspection
- **Project Export**: Generates runnable React/TypeScript projects from Manifest source
- **Computed Properties**: Derived values that auto-update based on dependencies
- **Guard Diagnostics**: Detailed failure reporting with resolved expression values
- **Policy Enforcement**: Authorization checks before command execution
- **vNext Features**: Constraint severity/outcomes, override authorization, workflow idempotency, entity concurrency controls

### Language Features

- **Entities**: Define data structures with properties, defaults, and modifiers (`required`, `unique`, `readonly`, etc.)
- **Commands**: Business operations with parameters, guards, actions (`mutate`, `emit`, `compute`), and event emissions
- **Guards**: Boolean expressions evaluated in order; execution halts on first failure
- **Policies**: Authorization rules scoped to entities and actions (`read`, `write`, `execute`, `all`)
- **Events**: Typed event definitions with channels and payload schemas
- **Stores**: Persistence targets (`memory`, `localStorage`, with adapters for `postgres`, `supabase`)
- **Modules**: Logical grouping of related entities, commands, and policies
- **Computed Properties**: Derived values with explicit dependency tracking, with optional memoization (`cache request` / `session` / `ttl`)
- **Relationships**: Declarative relationships (`hasMany`, `hasOne`, `belongsTo`, `ref`)
- **Constraint & Expression Builtins**: `matches(value, pattern)` regex constraints (compile-time pattern validation + runtime enforcement), aggregate builtins over collections (`sum`, `avg`, `min_of`, `max_of`, `count_of`, `filter`, `map` with optional mapper lambdas), and `flag(name)` feature-flag resolution in guards/policies

## Getting Started

**New to Manifest?** Start with the [Usage Patterns Guide](docs/guides/usage-patterns.md) to understand the two ways to integrate Manifest into your application:

1. **Projections** - Auto-generate API routes from `.manifest` files (best for simple CRUD)
2. **Embedded Runtime** - Use the runtime directly in your handlers (best for complex workflows)

Most applications use both patterns together.

## Projection System

The projection system generates platform-specific code from Manifest IR. Projections are **tooling**, not runtime semantics—they consume IR and emit artifacts like API routes, type definitions, and client SDKs.

### Next.js Projection

The Next.js projection includes 12 surfaces: `route`, `detail`, `command`, `dispatcher`, `subscribe`, `subscriptionHook`, `sharedRuntime`, `schedule`, `webhook`, `companions`, `ts.types`, `ts.client`, and `all` (aggregate).

### Projection Design Principles

From `docs/guides/writing-projections.md`:

- **Reads MAY bypass runtime**: Entity routes use direct DB queries for performance (read policies not enforced by default)
- **Writes MUST use runtime**: Command routes enforce guards, policies, constraints, and event emission
- **Configurable auth**: Support multiple auth providers without hardcoding
- **Tenant isolation**: Optional tenant filtering for multi-tenant applications
- **Platform-specific**: Projections adapt to platform conventions (Next.js App Router, Express, Hono edge runtimes)

In addition to Next.js, the following projections are available via the registry (`src/manifest/projections/`): `prisma`, `drizzle`, `openapi`, `graphql`, `zod`, `react-query`, `jsonschema`, `express`, `hono`, `mermaid`, and `llm-context`. Generate diagrams from the CLI with `manifest diagram`.

See `src/manifest/projections/nextjs/README.md` for detailed usage examples.

## Architecture

```
┌─────────────────┐
│ Manifest Source │ (.manifest files)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   IR Compiler    │ (lexer → parser → IR transformation)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   IR v1 JSON    │ (canonical contract)
└────────┬────────┘
         │
         ├─────────────────┬──────────────────┬────────────────┐
         ▼                 ▼                  ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Runtime    │  │  Export      │  │  Conformance│  │ Projections  │
│   Engine     │  │  Templates   │  │  Tests      │  │ (Next.js)    │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘
```

### Core Components

- **`src/manifest/lexer.ts`**: Tokenizes Manifest source code
- **`src/manifest/parser.ts`**: Parses tokens into AST
- **`src/manifest/ir-compiler.ts`**: Transforms AST to IR v1
- **`src/manifest/runtime-engine.ts`**: Executes IR commands with full semantics
- **`src/manifest/projections/`**: Platform-specific code generators
  - **`nextjs/`**: Next.js App Router projection with 12 surfaces (route, detail, command, dispatcher, subscribe, subscriptionHook, sharedRuntime, schedule, webhook, companions, ts.types, ts.client, all)
  - **`interface.ts`**: Projection contracts and options
  - **`registry.ts`**: Projection registration and lookup
- **`src/manifest/conformance/`**: Executable test fixtures (101 .manifest source files; run `pnpm test` for current expected outputs count)
- **`src/artifacts/`**: Runtime UI components for development and testing
- **`src/project-template/templates.ts`**: Code generators for exported projects
- **`bin/generate-projection.ts`**: CLI tool for code generation
- **`docs/spec/`**: Language specification (IR schema, semantics, builtins, adapters)
- **`docs/guides/writing-projections.md`**: Critical documentation on the projection boundary

## Example Program

```manifest
entity PrepTask {
  property required id: string
  property required name: string
  property assignedTo: string?
  property status: string = "pending"
  property priority: number = 1

  computed isUrgent: boolean = priority >= 3

  command claim(employeeId: string) {
    guard self.status == "pending"
    guard user.role == "cook" or user.role == "chef"
    mutate assignedTo = employeeId
    mutate status = "in_progress"
    emit taskClaimed
  }

  command complete() {
    guard self.status == "in_progress"
    guard self.assignedTo == user.id
    mutate status = "completed"
    emit taskCompleted
  }

  policy canClaim execute: user.role in ["cook", "chef"]
}

store PrepTask in memory

event taskClaimed: "kitchen.task.claimed" {
  taskId: string
  employeeId: string
}

event taskCompleted: "kitchen.task.completed" {
  taskId: string
  completedBy: string
}
```

## For AI Agents: Critical Constraints

This repository enforces **strict semantic invariants**. Read `AGENTS.md` and `docs/internal/contracts/house-style.md` before making changes.

### Core Invariants

1. **Determinism**: Identical IR + identical runtime context = identical results
2. **Explicitness**: Guards MUST reference spec-guaranteed bindings (`self.*`, `this.*`, `user.*`, `context.*`)
3. **Strict Execution Order**: Policies → Guards → Actions → Emits (no shortcuts)
4. **IR Immutability**: IR is immutable at runtime; all variability via runtime context
5. **Spec-First Workflow**: Spec changes → Tests → Implementation (never reverse)

### Source of Truth (Priority Order)

1. `docs/spec/ir/ir-v1.schema.json` - IR shape is the contract
2. `docs/spec/semantics.md` - Runtime meaning
3. `docs/spec/builtins.md` - Built-in identifiers/functions
4. `docs/spec/adapters.md` - Adapter hooks
5. `src/manifest/conformance/*` - Executable evidence

### Non-Negotiables

- ❌ **Never edit IR output by hand** - IR is compiler output, always derived
- ❌ **Never weaken conformance** - If tests "feel too strict," the agent is wrong
- ❌ **Never fix UI by changing semantics** - UI adapts to language, not reverse
- ❌ **Never make invalid programs succeed** - That's a language violation, not UX improvement

### Required Workflow

For any change:

1. **Determine purpose**: Language change (meaning) or tooling change (projection)?
2. **Locate governing law**: Find exact spec sections and conformance fixtures
3. **Update in order**: Spec → Tests → Implementation (if meaning changes)
4. **Prove it**: `pnpm test` must pass; document any nonconformance

## Development

### Prerequisites

- Node.js >=20
- pnpm

### Setup

```bash
pnpm install
```

### Commands

- `pnpm test` - Run all tests (must pass)
- `pnpm run test:watch` - Run tests in watch mode
- `pnpm run dev` - Start development server with Runtime UI
- `pnpm run conformance:regen` - Regenerate expected IR outputs from fixtures
- `pnpm run bench` - Run performance benchmarks
- `pnpm run build` - Build for production
- `pnpm run typecheck` - TypeScript type checking
- `pnpm run lint` - ESLint validation

### Manifest CLI

The `manifest` CLI (see `packages/cli`) exposes the toolchain. Notable commands:

- `manifest compile` / `manifest generate` / `manifest build` - compile source to IR and emit projections
- `manifest validate` / `manifest validate-ai` - validate programs (the latter scores IR for LLM consumers)
- `manifest watch` - incremental re-compile/re-project on `.manifest` file changes
- `manifest diagram` - emit Mermaid ER/diagram output from IR
- `manifest coverage` - report command/guard/policy/constraint coverage from test runs
- `manifest changelog` - generate a changelog from IR diffs between tags
- `manifest diff` / `manifest breaking` - IR diff and breaking-change detection
- `manifest fmt` - deterministic source formatter
- `manifest migrate`, `manifest doctor`, `manifest audit-governance`, `manifest integration-check`

### Projection CLI

Generate platform-specific code from Manifest IR (dev-only, uses tsx):

```bash
# Generate a Next.js entity route (GET operations)
npx tsx bin/generate-projection.ts nextjs nextjs.route recipe.manifest Recipe --output route.ts

# Generate a Next.js command route (POST/PUT/DELETE operations)
npx tsx bin/generate-projection.ts nextjs nextjs.command recipe.manifest Recipe create --output route.ts

# Generate TypeScript types
npx tsx bin/generate-projection.ts nextjs ts.types recipe.manifest --output types.ts

# Generate client SDK
npx tsx bin/generate-projection.ts nextjs ts.client recipe.manifest --output client.ts

# Configure auth provider
npx tsx bin/generate-projection.ts nextjs nextjs.route recipe.manifest Recipe --auth clerk --output route.ts

# List available projections
npx tsx bin/generate-projection.ts --list

# Show help
npx tsx bin/generate-projection.ts --help
```

**Note**: The CLI is a development tool using `tsx`. For production use, import the projection functions directly into your build scripts.

**Important**: Entity routes (nextjs.route) generate READ operations that bypass the runtime (direct DB queries). Command routes (nextjs.command) MUST use `RuntimeEngine.runCommand()` for mutations. See `docs/guides/writing-projections.md` for detailed rationale.

### Testing

Run `pnpm test` for the current test count (this is an actively developed codebase — hard counts go stale quickly).

**Conformance Suite** (`src/manifest/conformance/conformance.test.ts`):

- 101 fixture files (`.manifest` source files)
- Expected outputs (IR, diagnostics, runtime results)
- Validates IR compilation correctness
- Runtime command execution semantics
- Guard and policy evaluation
- Event emission
- Computed property evaluation
- Instance creation with defaults
- vNext features (constraints, overrides, workflows, concurrency)

**Unit Tests**:

- Lexer tests (58): Tokenization and edge cases
- Parser tests (79): AST construction
- IR Compiler tests (91): IR generation and normalization
- Runtime tests (56): Command execution, guards, policies

**Projection Tests** (21 tests):

- Next.js projection smoke tests
- Verifies all 4 surfaces (route, command, types, client)
- Auth provider configurations
- Tenant and soft-delete filtering

All tests use deterministic time and ID generation for reproducibility.

## Project Structure

```
.
├── bin/                    # CLI tools
│   └── generate-projection.ts  # Projection code generator
├── docs/
│   ├── spec/              # Language specification
│   │   ├── ir/
│   │   │   └── ir-v1.schema.json  # IR schema (authoritative contract)
│   │   ├── semantics.md    # Runtime meaning and execution model
│   │   ├── builtins.md     # Built-in identifiers and functions
│   │   ├── adapters.md     # Adapter hooks and contracts
│   │   ├── conformance.md  # Test rules and fixture contracts
│   │   ├── manifest-vnext.md  # vNext features documentation
│   │   └── README.md       # Spec overview (IR-first principles)
│   ├── migration/
│   │   └── vnext-migration-guide.md  # vNext migration guide
│   ├── patterns/
│   │   └── external-projections.md  # Projection boundary documentation
│   └── tools/             # Tool documentation and usage guides
├── src/
│   ├── manifest/          # Core language implementation
│   │   ├── lexer.ts        # Tokenizer
│   │   ├── parser.ts       # AST parser
│   │   ├── ir-compiler.ts  # IR transformation
│   │   ├── runtime-engine.ts # Command execution engine
│   │   ├── compiler.ts     # Main compiler orchestrator
│   │   ├── types.ts        # TypeScript type definitions
│   │   ├── ir.ts           # IR data structures
│   │   ├── version.ts      # Version constants
│   │   ├── projections/    # Platform-specific code generators
│   │   │   ├── interface.ts    # Projection contracts (ProjectionTarget, ProjectionRequest)
│   │   │   ├── registry.ts     # Projection registration and lookup
│   │   │   ├── builtins.ts     # Built-in projection utilities
│   │   │   └── nextjs/
│   │   │       ├── generator.ts      # Next.js projection implementation
│   │   │       ├── generator.test.ts # 21 smoke tests
│   │   │       └── README.md         # Usage documentation
│   │   ├── conformance/    # Test fixtures & expectations
│   │   │   ├── conformance.test.ts  # Conformance tests
│   │   │   ├── fixtures/   # 101 .manifest test files
│   │   │   └── expected/   # Expected outputs (.ir.json, .diagnostics.json, .results.json)
│   │   ├── *.test.ts       # Unit tests (lexer, parser, ir-compiler, runtime)
│   │   └── *.bench.ts      # Performance benchmarks
│   ├── artifacts/          # Runtime UI components
│   │   ├── ArtifactsPanel.tsx   # Generated code viewer
│   │   ├── RuntimePanel.tsx     # Interactive execution tester
│   │   ├── SmokeTestPanel.tsx   # Smoke testing UI
│   │   ├── FileTree.tsx         # File navigation
│   │   ├── FileViewer.tsx       # Code viewer
│   │   └── zipExporter.ts       # Project packaging
│   ├── project-template/   # Code generators for exported projects
│   │   ├── templates.ts    # Code generation templates
│   │   └── runtime.ts      # Runtime utilities
│   └── ui/                # UI components
├── tools/                 # Development tools and test harnesses
├── AGENTS.md             # Agent workflow rules and loop discipline
├── CLAUDE.md             # Project guidance for Claude Code
└── docs/internal/contracts/house-style.md        # Language design principles
```

## Key Concepts for AI Agents

### Instance Creation & Defaults

When creating an instance:

- **Omitted properties** receive default values from property definitions
- **Provided properties** (even empty strings `""`) use the provided value
- UI forms filter empty strings to allow defaults to apply (see `templates.ts`)

### Command Execution Semantics

Commands execute in strict order:

1. Build evaluation context (`self`, `this`, params, runtime context)
2. Evaluate applicable policies (fail fast on denial)
3. Evaluate guards in order (fail fast on first falsey guard)
4. Execute actions in order (`mutate`, `emit`, `compute`, etc.)
5. Emit declared events
6. Return `CommandResult` with success status and emitted events

### Guard Failures

When a guard fails, the runtime provides:

- Guard index (1-based)
- Formatted expression
- Resolved values for sub-expressions (for debugging)

### Event Payloads

Event payloads contain:

- Command input parameters
- Last action result

This enables event handlers to reconstruct the full execution context.

## Contributing

See `AGENTS.md` for detailed workflow requirements. Key points:

- All changes must pass `pnpm test`
- Spec changes require updating fixtures and expected outputs
- UI changes must not alter language semantics
- Document any nonconformance explicitly

## License & Status

Licensed under the [MIT License](LICENSE).

This is a language implementation project. The Runtime UI is a diagnostic and observability surface, not an end-user application.

**Primary consumers**: AI agents that emit, validate, and reason about Manifest programs.

---

For detailed agent workflow rules, see [`AGENTS.md`](AGENTS.md).  
For language house style and invariants, see [`docs/internal/contracts/house-style.md`](docs/internal/contracts/house-style.md).  
For the complete specification, see [`docs/spec/README.md`](docs/spec/README.md).