12 · Grammar Specification (EBNF & Conformance)
This page formalizes AgentMark v0.2 into an implementable grammar: a context-free syntax (EBNF) plus the lexical rules, enumerations, conformance profiles, and well-formedness constraints a parser/compiler needs.
0 · Status & scope
- Language version: 0.2.0 (experimental).
- Encoding: UTF-8. Source files use the
.agentmarkextension. - Newlines: LF canonical; CRLF accepted on input, normalized to LF.
- Indentation: significant. Exactly two (2) spaces per level. Tabs are prohibited where indentation is meaningful.
- Goal: a single file is the source of truth; the grammar must round-trip without loss, which is why nodes carry stable IDs.
2 · Lexical grammar
Char ::= #x9 | #xA | #xD | [#x20-#x10FFFF]
NodeType ::= Letter (Letter | Digit)*
Ident ::= Letter (Letter | Digit | "_")*
Number ::= "-"? Digit+ ("." Digit+)?
Bool ::= "true" | "false"
Date ::= Digit Digit Digit Digit "-" Digit Digit "-" Digit Digit
Quantity ::= "$"? Magnitude ("/" Unit)?
3 · Document structure
Document ::= Frontmatter? Body
Body ::= ( Heading | TopologyStmt | KnowledgeBlock | BlankLine )*
TopologyStmt::= EdgeStmt | NodeDecl
A Sketch-profile document may omit the frontmatter and contain only TopologyStmts.
4 · Topology grammar
Node ::= "[" NodeType ("#" NodeId)? (":" Label)? (Props)? "]"
Props ::= "{" PropPair ("," PropPair)* "}"
EdgeStmt ::= EdgeInline | EdgeFanout
EdgeInline::= Node (Arrow EdgeLabel? Node)+
Arrow ::= "<->" | "->" | "=>" | "x>" | "~>"
EdgeLabel ::= "[" (Char - ("]" | NL))+ "]"
Arrow semantics (closed set):
| Arrow | Meaning |
|---|---|
-> |
uses / calls / sends to |
=> |
hands off / escalates to |
x> |
blocks / forbids |
~> |
observes / subscribes to |
<-> |
interacts with (two-way / channel) |
The lexer matches the 3-character <-> before the 2-character arrows.
Two disambiguation rules a lexer MUST apply: (1) Edge-label vs node — a [...] is an EdgeLabel iff it immediately follows an Arrow with no whitespace (->[label]); separated by whitespace (-> [Node]) it is a Node. (2) Fan-out vs chain — an indented arrow block originates every arrow from the head node (fan-out); a genuine pipeline (a→b→c→d) MUST be written inline on one line.
6 · Values & enumerations
Closed enumerations:
| Enum | Allowed values |
|---|---|
| ReqLevel (RFC 2119) | MUST, MUST_NOT, SHOULD, SHOULD_NOT, MAY |
| Confidence | low, medium, high, very_high |
| Risk | low, medium, high, critical |
| RadarRing | adopt, trial, assess, caution, blocked |
| Status (decision) | draft, proposed, accepted, rejected, superseded, deprecated |
| Volatility | low, medium, high |
| Verdict (interceptor) | allow, warn, block, review |
8 · Conformance profiles
| Level | Name | Adds | Frontmatter | Use |
|---|---|---|---|---|
| L0 | Sketch | Node, EdgeStmt only (four arrows, optional labels) | optional | whiteboard, posts, virality |
| L1 | Spec | #id, Label, Props, fan-out, frontmatter | required (agentmark, title) | engineering diagrams |
| L2 | Decision | all KnowledgeBlocks, references, conditions, matrices, views | required + as_of / review_by | time-sensitive AI architecture |
9 · Well-formedness rules (static semantics)
W-1 [L2] Any block carrying a time-sensitive statement MUST include as_of AND review_by.
W-2 [L2] Any comparative statement (claim.kind = comparative) MUST include scope AND metric.
W-3 [L1] Every Node's NodeType MUST be a member of the stable node-type vocabulary.
W-4 [L2] Every decision SHOULD link to supported_by (claims) and/or constrained_by (constraints).
W-5 [L2] Block IDs MUST follow their prefix convention: constraints K-, claims C-, decisions D-.
W-6 [L2] Any claim used by a decision MUST have confidence AND evidence.
W-7 [L2] Every matrix MUST carry provenance: as_of, scope, evidence; SHOULD carry method, confidence, review_by.
W-8 [L1] In strict mode, unknown field keys for a block type are errors; in lax mode they are warnings.
W-9 [L1] Every #id referenced MUST resolve to exactly one declared node. IDs are unique per document.
W-10 [L2] Every BareId reference (C- / K- / D- / bench# / test#) MUST resolve to a declared block.
W-11 [L2] view.show entries MUST be valid node types or block keywords.
W-12 [L2] Any node exposing a high-risk capability (risk = high or critical) MUST link to a policy, approval, or authority.
W-13 [L2] A decision is reported STALE if today > review_by, or any invalid_if condition holds, or a referenced claim has expired.
W-14 [L1] Indentation MUST be a multiple of two spaces; tabs in indentation are errors.
W-15 [L0] An EdgeLabel MUST immediately follow its Arrow (no whitespace); otherwise the bracket is parsed as a target node.
10 · Reserved words
Block keywords: constraint, claim, decision, landscape, matrix, bench, test, view, authority, trust, observability, recommendation, tradeoff, capability, assert.
Grammar status: draft, tracks language v0.2.0 · Owner: Joel Tong.