# §1 · Scope, conformance, and notation

> **Status: DRAFT.** Claims marked ⚑ were probed against the compiler; the probe is named. Claims marked
> **UNVERIFIED** were not, and must not be relied on.

## 1.1 Scope

This document specifies the Osy# language: its lexical structure, types, declarations, expressions, and the
semantics a conforming implementation must give them.

Osy# is unusual in three ways that the specification must cover explicitly, because a reader arriving from C# will
assume otherwise:

1. **A program spans two execution sides.** One source unit compiles into code that runs in a browser and code that
   runs on a server. Which side a member runs on is **inferred** (§6), not declared.
2. **Execution is durable.** A call may suspend and resume in a different process (§9). This is not a library
   facility; it changes what an expression means, and it is why some C# constructs are refused (§11).
3. **Authorization is part of the language.** Access rules are declared on a type and enforced beneath every read
   and write (§8). No program text can bypass them.

The runtime, the toolchain (`osy …`), the bundled UI kit, and the platform's hosted services are **outside**
this scope. They are specified where they change the meaning of a program, and only there.

## 1.2 Conformance

A **conforming implementation** accepts every program this specification defines as valid, and rejects every
program it defines as invalid, with a diagnostic.

⚠ **Diagnostics are part of the contract, not an implementation detail** (§12). Osy# refuses a great deal on
purpose, and a refusal that does not say what to write instead is a defect in the implementation, not a matter of
taste. Where this specification defines a refusal it also states what the diagnostic must convey.

## 1.3 What is normative

Normative text uses **MUST**, **MUST NOT**, **MAY** in the usual sense.

Everything else — rationale, comparisons to C#, notes on why a rule exists — is **informative**. It is kept
because for this language the reasons are frequently the useful part, but a conforming implementation is judged
only against the normative text.

## 1.4 Notation

Grammar is given in a bracketed EBNF:

| form | meaning |
|---|---|
| `x?` | optional |
| `x*` | zero or more |
| `x+` | one or more |
| `x \| y` | alternatives |
| `( … )` | grouping |
| `'text'` | a literal token |
| *italic* | a non-terminal defined elsewhere in this document |

⚠ **The grammar in this document is written FROM the parser, and is not itself the parser.** Where the two
disagree the parser is correct and this document has a bug — report it rather than working around it. Sections
whose grammar has been checked against a probe say so; sections that have not are marked **UNVERIFIED**.

## 1.5 How claims in this document are established

Every normative claim is expected to carry one of:

- ⚑ **a probe** — the smallest program that distinguishes the claim, and what `osy validate` answered;
- **a test** — a named test class that asserts the behaviour, for anything `validate` cannot see (runtime
  semantics, durability, security enforcement);
- **UNVERIFIED** — stated but not established. Treat as a lead.

This is not ceremony. Three documents in this repository were deleted in the month before this specification was
started, each for confidently describing surface the language no longer had. The difference between those and this
one is meant to be the probe.