Language principles

These are the design rules IntentLang holds itself to. The manifesto says why the language exists; this page says why the language is shaped the way it is. Every construct, diagnostic, and compiler decision traces back to one of these.

1. Meaning is the source of truth

A .intent file records what software should do, why it matters, and what must never happen, before any implementation exists. Code is a target, not the record. When code and intent disagree, the intent is the thing under review, not silently overwritten. This is what makes the file durable while prompts, branches, and frameworks come and go.

2. Deterministic by default, AI by exception

The compiler must produce the same contract, plan, and proof from the same source every time, with --no-ai and no network. AI is an optional assist that only ever proposes; it never decides. Every AI action carries provider, model, prompt hash, input and output hashes, and a human approval status. If a result cannot be reproduced without a model, it is not part of the deterministic core.

3. A guarantee is only real when something proves it

An unverified guarantee is exactly where Intent Drift hides, so the language treats one as an unfinished thought. Every guarantee and never should carry a verify, and the compiler warns (guarantee-without-verification, never-without-verification) when it does not. Claims and proofs are different kinds of thing, and the language keeps them visibly separate: an accessibility_target or an inferred lift is always a proposed claim, never an IntentLang-verified fact.

4. Say what must never happen, not only what should

Most specifications describe the happy path. Software fails on the paths nobody wrote down. never rules are first-class precisely because forbidden behavior, a leaked secret, a double charge, an unapproved action, is where the expensive failures live. A mission is not complete until its prohibitions are as explicit as its goals.

5. Structure over prose

Intent is written in blocks the compiler understands (goal, input, output, guarantee, never, decision, lifecycle, test), not free text it has to guess at. Structure is what lets the same file become a contract graph, a test plan, a diagram, a runtime guard, and a proof, without a language model in the loop. Prose belongs in notes, which explain meaning to a reader and are never mistaken for verification.

6. Above paradigms, not against them

IntentLang does not replace TypeScript, Python, Java, .NET, Rust, or Go, and it does not pick object-oriented over functional or service-oriented over event- driven. It sits above them and targets each through an adapter. The same mission can emit clean-architecture C#, a functional core, an OpenAPI spec, or a Mermaid diagram. The intent is portable; the idioms are the target's.

7. Explainable, never oracular

The compiler never says "a possible issue was detected." Every diagnostic names its rule, the source it fired on, why it matters, and how to fix it. Every decision is traceable to a rule; every finding is deterministic or explicitly flagged as inferred and requiring human review. A person can always ask "why?" and get a real answer, not a confidence score.

8. Humans own the result

The compiler proposes, gates, and proves; it does not approve. Approvals bind to a reviewed hash and go stale the moment the thing they approved changes, so trust is never inherited by accident. Governance is on the record: a blocker can be waived, but only with an owner, a reason, and an expiry.

9. Additive and versioned

The language and its schemas are pre-1.0 and evolve, but they evolve without breaking what already parses. New fields are additive; persisted graphs migrate across schema versions deterministically. A .intent file written today should still mean the same thing tomorrow, and old proofs should still verify.

10. Honest about its limits

IntentLang catches the mistakes prompts ship and the drift code accumulates. It does not claim to prove a program correct. A lifted draft is inferred, not verified; a passing check means "no violation was found," not "nothing can go wrong." The value is in making purpose explicit and drift detectable, and the language says so plainly rather than overclaiming.

See also: the Manifesto for the vision, Intent-oriented programming for the practice, and the Syntax overview for the mechanics.