<!-- Sema documentation — §2. Surface syntax decision
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.49.12.246.95.sslip.io/llms-full.txt
     Install language support: https://sema.49.12.246.95.sslip.io/install-skill/ -->

# §2. Surface syntax decision

> Sema language specification — §2 Surface syntax decision.

> Generated from `docs/LANGUAGE.md` §2. This is the normative specification; for a guided tour see the Language and Neurosymbolic sections.

**Decision: Python-style indentation syntax (`:` + indent blocks), `def`/decorators/
keyword arguments retained — `struct` + `enum` + traits (§3.9) replace `class`; explicitly not
a superset; PEG grammar with soft keywords; edition field in the manifest from v0.1.**

Rationale ([12 §1–2](./research/12-syntax-dx.md)):

- The founder base and the ML ecosystem are Python-first; adoption empirics say familiarity,
  interop, and existing code dominate intrinsic features
  ([Meyerovich & Rabkin, OOPSLA 2013](https://dl.acm.org/doi/10.1145/2509136.2509515)).
- Code LLMs transfer best to languages syntactically close to a high-resource anchor
  ([MultiPL-T](https://arxiv.org/abs/2308.09895)); a Pythonic Sema maximizes zero-shot prior
  transfer and makes the Python→Sema synthetic-corpus pipeline nearly mechanical.
- Mojo proved the superset promise is a trap and "Pythonic + interop" is the stable landing
  ([Mojo FAQ](https://mojolang.org/docs/faq/)); Codon's documented list of dynamic features
  that break static compilation (monkey-patching, metaclasses, heterogeneous collections,
  dynamic member addition — [Codon](https://github.com/exaloop/codon)) is adopted as Sema's
  published "differences from Python" divergence spec.
- New constructs are `def`-modifiers (`simulate def`, like `async def`) or soft keywords under
  a PEG grammar (CPython [PEP 617](https://peps.python.org/pep-0617/)/
  [PEP 622](https://peps.python.org/pep-0622/) precedent), so post-1.0 keywords never break
  identifiers; a Rust-style edition mechanism
  ([Edition Guide](https://doc.rust-lang.org/edition-guide/editions/)) handles hard
  promotions.

**Rejected alternatives:** braces family (Rust/Go surface) — abandons the audience and the LLM
prior for tooling benefits tree-sitter already neutralizes; Python superset — Codon/Mojo
demonstrate the compatibility tax and credibility burn; new exotic syntax — zero evidence any
intrinsic-syntax bet has ever driven adoption ([12 §7](./research/12-syntax-dx.md)).

Keyword disposition versus the brief (evidence-driven changes flagged; details in §5 and the
Decision record):

| Brief keyword | Disposition |
|---|---|
| `semantics` | **kept** (expression predicate + block guard) |
| `simulate` | **kept** (`simulate def` modifier) |
| `testable` | **changed: verification is default-on**; `assure`/`@no_verify` replace the opt-in keyword |
| `policy` | **kept** (declaration + attachment) |
| `monitor` | **kept** (declaration form), collision risk documented |
| `native` | **split**: `native` = bind (C ABI/FFI), `ported` = toolchain-deterministic translation |
| self-healing | **scoped, not global**: `supervise`/`heal` blocks; repair-only, "extend/grow" scoped out (D14); phase sequencing per ROADMAP |

---
