CNL Programming Language
Controlled Natural Language for Executable Meaning
Wiki

Shared language and working conventions.

This wiki defines the vocabulary and internal conventions that keep CNL-PL consistent across specs, tooling, and evaluation.

Guides

Detailed walk-throughs that connect syntax, compilation, and reasoning.

Glossary

Common terms used throughout the documentation and codebase.

Term Category Definition
API Software Application Programming Interface. Defines how external systems interact with the CNL session, learn new theories, or execute pragmatic commands.
AST Compiler Abstract Syntax Tree. The tree-like structure that represents the grammatical structure of the CNL code after parsing. In CNL-PL, the AST is "lossless" (preserves spans) and deterministic.
Atomic Sentence Syntax The minimal statement form (subject + typed predicate) that can become a fact or a rule literal. Example: "Package_1 is heavy."
Assertion Syntax An atomic statement that asserts a fact about the world, expressed as a typed SVO triplet. Example: "Server_1 handles payments."
Condition Logic A boolean structure built from assertions, with explicit grouping rules. Example: "Both the user is active and the user is verified."
Aggregation Syntax A numeric expression over a set, such as counts or sums. Example: "The number of packages is greater than 10."
Comparator Syntax A comparison operator used with numeric expressions, such as "greater than" or "equal to".
Action Block Syntax A multi-line structure that defines an action's signature, the agent performing it, its preconditions, and its effects. Example: "Action: assign a driver to a route."
ActionPlan IR The compiled structure of an action, containing optimized SetPlan/BoolPlan trees for preconditions and effect deltas for the KB.
Action Signature Planning The verb phrase and object that identify an action. Example: "assign a driver to a route".
Precondition Planning A boolean requirement that must hold before an action executes. Example: "the route is unassigned".
Effect Planning The KB change produced by an action. Example: "the driver is assigned to the route".
Verb Phrase Syntax A structured predicate record that captures copula, verb, particles, and comparators so predicate IDs are deterministic. Example: "is assigned to".
AttrID Runtime A dense numeric index uniquely identifying an attribute (e.g., "capacity", "status") within the Knowledge Base.
Attribute Semantics A named property stored as numeric or entity-valued data. Example: "capacity", "status".
BFS Algorithm Breadth-First Search. An algorithm used in reasoning primitives (e.g., finding shortest proof paths or minimal hypothesis sets).
Bitset Technical A high-performance data structure used by the CNL engine to store relations and sets of entities, enabling near-instant queries.
BoolPlan IR A plan fragment that evaluates to a boolean (true/false) against the KB state.
CI DevOps Continuous Integration. The automated testing pipeline that verifies CNL-PL's correctness on every change (see DS05 Testing Plan).
CNL-PL Project Controlled Natural Language Programming Language. The name of this language and system, designed to be readable like English but executable like logic.
CSP Solving Constraint Satisfaction Problem. A mathematical problem defined by a set of objects whose state must satisfy a number of constraints or limitations (used in the 'Solve' pragmatic).
Canonical Form Theory The standardized internal representation of a sentence. For example, "X > Y" is canonicalized to "X is greater than Y".
ConceptualID Identity A stable, 64-bit identifier for any symbolic concept (entity, predicate, attribute). It remains constant across sessions, unlike dense IDs.
DAG Structure Directed Acyclic Graph. Used to represent justification chains in proofs and explanations, preventing circular reasoning.
DS Specs Design Specification. The prefix for formal design documents (e.g., DS01, DS03) that define the authoritative behavior of the system.
Determinism Theory The rule that every valid sentence yields exactly one AST. Inputs with multiple parses are rejected instead of guessed.
EBNF Syntax Extended Backus-Naur Form. A notation used to formally describe the grammar rules of CNL-PL (see DS03).
EOF Parser End Of File. A token marking the end of the input stream, important for validation rules.
EntityAttrIndex Storage A KB structure optimized for storing entity-valued attributes (e.g., "owner" -> EntityID).
EntityID Runtime A dense numeric index (0..N) representing an entity in the current session's KB.
FactID Runtime A unique identifier (usually a hash) for a specific fact (SVO triplet) in the Knowledge Base, used for provenance and explaining "why" something is true.
Ground Fact Compiler An atomic sentence that can be inserted into the KB because all required terms resolve to concrete entities or literals.
Grounding Compiler The step where the compiler decides which sentences become KB facts and which become plans or rules.
IDENT Lexer A token type representing an identifier (name, attribute, or noun core), distinct from keywords and literals.
IR Compiler Intermediate Representation. A specialized format (Plan IR) used between the AST and the runtime execution engine (see DS16).
Interning Compiler The process of converting repetitive strings (like entity names or predicates) into unique integer IDs to optimize memory and speed.
JSON Data JavaScript Object Notation. The format used for AST snapshots, configuration, and evaluation suite outputs.
KB Runtime Knowledge Base. The in-memory database that stores compiled facts, relations, and indices (DS09).
Image Reasoning A primitive that maps a set of subjects to all reachable objects through a predicate.
Preimage Reasoning A primitive that maps a set of objects to all subjects that reach them through a predicate.
Inverse Index Storage The reverse RelationMatrix used to answer "who points to this object" in O(1) bitset time.
State Overlay Runtime The logical view that combines the base KB with a temporary delta layer.
Delta Layer Runtime The temporary set of adds/removes applied during planning or simulation steps.
NumberPlan IR A plan fragment that evaluates to a numeric value (e.g., aggregation results like "total cost").
NumericIndex Storage A column-oriented KB structure for storing numeric attribute values (float64/int32).
Pragmatics Architecture The "intent" or execution mode applied to a sentence. The same text can be a Question (Query), a Verification (Verify), or a Goal (Plan).
Query Pragmatics The mode that evaluates conditions and returns entity sets or projected values (for example, "Command: Return the name of every active user.").
Verify Pragmatics The mode that checks whether a proposition is derivable (for example, "Command: Verify that every server is encrypted.").
Proof Pragmatics The underlying derivation engine used by Verify; it can also emit a proof trace instead of a boolean. Example: "Rule_12 + premises".
Explain Pragmatics The mode that returns the justification chain for a derived fact, optionally surfaced as base fact sentences (for example, "Command: Explain why Server_1 is encrypted.").
Plan Pragmatics The mode that searches for an action sequence that achieves a goal condition (for example, "Command: Plan to achieve all packages delivered.").
Solve Pragmatics The mode that binds variables to satisfy constraints, often treated as a CSP (for example, "Command: Find a route such that the route is feasible.").
Variable Binding Solving The assignment of concrete entities to variables so a constraint becomes true.
Simulate Pragmatics The mode that applies transition rules step-by-step to evolve state (for example, "Command: Simulate 5 steps.").
Optimize Pragmatics The mode that maximizes or minimizes an objective under constraints (for example, "Command: Minimize the total cost of the route.").
PredID Runtime A dense numeric index representing a binary relation (verb phrase) in the KB.
Relation Semantics A typed verb phrase that links a subject to an object.
Binary Relation Storage A subject-object relation stored in the RelationMatrix with forward and inverse indices.
PropID Runtime Identifier for a complex proposition (AND/OR/NOT tree) used in proofs, distinct from atomic FactIDs.
RelationMatrix Storage The core data structure for binary relations in the KB, implementing fast row/column access via Bitsets.
RelationPlan IR A plan fragment that produces a virtual relation (rows of Bitsets), used for complex joins.
Justification Provenance The recorded chain of rules and premises that explain why a derived fact holds. Example: "Rule_12 from Fact_3 and Fact_9".
Rule Logic An implication that derives new facts from conditions. Example: "A route is valid if the route is feasible."
Rule Body Logic The condition part of a rule (the "if" side) that must hold to trigger derivation.
Rule Head Logic The consequence part of a rule (the "then" side) that is derived when the body holds.
Constraint Logic A boolean condition that restricts valid states or solutions. Example: "every server is encrypted".
Transition Rule Simulation A rule of the form "when X occurs, then Y" used to evolve state over steps.
Provenance Provenance The stored derivation metadata that allows Proof and Explain to reference sources.
RuleID Runtime Unique identifier for a compiled rule, used to track provenance when a rule derives new facts.
RulePlan IR Executable plan for a rule, containing a body (conditions) and a head (effects/derivations).
SMT Backend Satisfiability Modulo Theories. A powerful class of solvers that can be used as a backend for the 'Proof' and 'Solve' pragmatics.
SVO Linguistics Subject-Verb-Object. The fixed structure of any atomic sentence in CNL.
Example: "John (S) knows (V) python (O)."
SetPlan IR A plan fragment that evaluates to a Bitset of entities (e.g., "all active users").
SymbolTable Runtime The bidirectional mapping between human-readable strings and internal ConceptualIDs.
Unary Predicate Runtime A property or type membership stored as a global bitset (e.g., \"is active\").
UnaryPredID Runtime A dense numeric index representing a unary predicate (e.g., "is active", "is a user").
UTF-8 Encoding The standard character encoding used for all CNL source files and inputs.

Key Concepts Detail

Assertion

The atomic statement form: subject, verb, object or controlled copula.

Condition

A boolean structure built from assertions, with explicit grouping rules.

Relative clause

A constraint attached to a noun phrase using explicit pronouns (who, which, that).

Project Conventions

  • All specs and documentation are written in English.
  • Design specifications are stored as DSxx markdown files.
  • AST shapes are lossless and preserve lexical spans.