# The `.one` source language

Every One project has one canonical authored language. A `.one` file combines
non-executable semantic items with isolated implementation claims without
merging their grammar, identity, or trust.

## Source units and items

Every source begins with its exact envelope revision:

```one
one 1
```

It then contains one or more top-level items. There are exactly two envelope
forms:

```one
semantic acme.orders
    domain one.product@1
    # declarations governed by the selected domain

impl acme.orders#OrdersRust@1
    realizes acme.orders#Orders@1
    using one.language.rust#OwnedAsync@1
    source
        // isolated source-language body
```

`semantic` selects one namespace and one primary domain. `impl` associates one
stable implementation claim with one semantic target and one exact language
profile. Co-location creates no reference, reachability, provider choice,
authority, or runtime activation.

## Indentation is structure

Four spaces form one canonical structural level. A greater indentation starts
the preceding head's child suite; a matching dedent closes it. Blank lines and
comment-only lines do not affect structure.

Tabs in structural indentation, inconsistent dedents, required empty suites,
children under scalar-only clauses, trailing block colons, and structural
braces are errors. A newline ends the current clause; indentation is not a
generic continuation mechanism.

Colons remain valid inside lines for typed fields and named arguments:

```one
record Order@1
    id: OrderId
    items: List<LineItem>
    @Invariant(total == sum(items[*].price))
```

Expression delimiters remain explicit: `List<T>`, `f(x)`, `items[*]`,
`1..=100`, and `@Length(1..=64)` do not acquire special layout rules.

## Identities, lanes, and exact revisions

`Order@1` names the `@1` compatibility lane of `Order`; the lock selects its
exact immutable revision. A declaration name, continuing identity, compatibility
lane, and exact revision are different things.

Source uses owner-qualified names where context does not already establish the
namespace. A friendly name resolves only when the selected source and lock make
it unambiguous. Later stages retain exact owner identities and never repeat
name search.

## Domain selection and imports

The first child of a semantic item is its primary domain:

```one
semantic acme.orders
    domain one.product@1
```

That domain supplies a closed public vocabulary: declaration heads, types,
traits, units, rules, defaults, and normalizers. There is no compiler-owned
hidden prelude.

Additional dependencies are definition-ordered `use` declarations:

```one
use acme.money.Money@3
use one.identity@1 only Principal, TenantId
use acme.compliance@1
use one.data@2 as data_v2
```

A symbol import binds its terminal name. A package import binds its terminal
namespace, such as `compliance.Control`. `only` is a finite one-line selective
import. `as` performs a category-preserving rename. Two identities or lanes
cannot occupy the same source name, and an import cannot silently shadow a
primary-domain export.

Imports precede first use. Local declarations and members are also
definition-ordered: a refinement can reference only imports, completed
declarations, and preceding members. Genuine recursion uses an explicit
domain-owned recursion group; unresolved forward references do not imply it.

## Structural types, collections, and relations

The selected domain may expose scalar and nominal types, records, variants,
references, and constructors such as:

```one
Text
Bytes
UInt
Decimal
Optional<T>
List<T>
Map<K, V>
```

Relations use `<`, `<=`, `==`, `!=`, `>=`, and `>`. Ranges use `start..end` or
inclusive `start..=end`. Both sides must have compatible owner-defined types or
dimensions.

## Typed quantities and units

A dimensional literal is a number followed directly by an exact,
case-sensitive unit symbol:

```one
timeout: 30s
retention: 7y
payload_limit: 16MiB
throughput: 100MiB/s
monthly_cost: <= 5_000USD
availability: >= 99.95%
```

Fixed durations and calendar periods remain distinct. `m` is a minute; `mo`
is a calendar month. `B`, `KiB`, and `MiB` are binary byte units, while `kB`
and `MB` are decimal. `b` is a bit. Case changes are semantic and are never
corrected heuristically.

The lexer recognizes quantity structure; the exact imported owner resolves the
unit and dimensional arithmetic. Equivalent forms normalize only when an
owner definition proves the conversion. Decimal normalization never depends on
binary floating-point rounding.

## Comments, formatting, and incomplete source

`#` introduces a System IDL comment where the selected language permits it.
The formatter preserves comments and malformed regions, uses four-space
structural indentation, keeps every `use` on one line, and never rewrites a
foreign implementation body.

Incomplete or malformed bytes remain the current authored state. Editors may
offer completion and patch candidates, but they cannot show a previous valid
semantic value as though it represented newer invalid source.

Next: [domains and traits](/one/authoring/domains-and-traits), then
[author a product](/one/authoring/product).