# Source and meaning

One separates what a system means from how it happens to be implemented. That
separation lets contracts survive changes in language, runtime, provider,
topology, and deployment strategy.

## The `.one` source envelope

Every source unit starts with one versioned envelope header and contains one or
more indentation-delimited items. There are exactly two envelope item kinds:

```one
one 1

semantic acme.orders
    domain one.contracts@1
    # Non-executable System IDL.
    service Orders@1

impl acme.orders_impl#OrdersRust@1
    realizes acme.orders#Orders@1
    using one.language.rust#SafeService@1
    source
        // Isolated Rust implementation body.
```

A semantic item selects its namespace and one primary semantic domain. An
implementation item names one stable implementation, one semantic target, and
one implementation-language profile. Its body is interpreted only by that
profile's exact language tools.

Physical co-location creates no semantic edge, import, lexical scope,
reachability, implementation choice, or authority. Every real relationship is
an explicit owned reference.

## System IDL is non-executable

System IDL declares stable meaning and governed intent:

- nominal types, schemas, constraints, compatibility, and faults;
- operations, services, jobs, workflows, and interaction contracts;
- state and transaction requirements;
- effects and authority requirements;
- applications, roots, areas, and explicit composition edges;
- provider-independent placement, quality, policy, and evidence requirements.

It does not run application code, choose providers, mint trusted IR, issue
grants, or create artifacts. A declaration can require durable state; it
cannot quietly choose PostgreSQL. It can require outbound communication; it
cannot grant network access.

## Meaning belongs to its domain owner

One owns its standard semantic distribution, not every domain an organization
may describe. A semantic item can select an organization-owned domain using
the same Contracts meta-model while keeping its own namespace, vocabulary,
normalization rules, and conformance.

Two domains compose through explicit directional mappings. A mapping records
what is preserved, transformed, defaulted, narrowed, widened, or lost. Sharing
the `.one` envelope never translates one owner's meaning into another's.

This makes custom domains independently useful: they can be checked,
distributed, implemented, planned, and inspected without pretending to be a
`one.*` contract.

## Source transactions power every editor

Canonical text does not require a text-only experience. An editor may render a
source item as text, a form, a table, a graph, a diagram, or synchronized
views. Every structured edit remains a bounded source transaction:

1. start from exact source revisions;
2. propose a reviewable patch;
3. reparse every complete affected input through the one parser;
4. rerun the applicable owner checks;
5. commit all source revisions atomically only if their bases are current.

Malformed text remains the current authored state. A tool never presents an
older valid model as though it represented newer invalid bytes, and no hidden
editor model becomes semantic authority.

## Stable identity, revisable syntax

Authored syntax is a projection of owned meaning. Grammar changes terminate at
the authoring boundary: parsing, formatting, source maps, and domain
normalization. Lower contracts depend on normalized owner values, not source
tokens, text order, parser trees, or field spelling.

Every declaration has an owner-qualified identity and an exact revision.
Digests commit complete owned records; they do not replace them. A tuple hash
cannot manufacture an artifact, provider realization, binding, grant,
deployment, or receipt.

## Navigate every definition and consequence

Editor hover, completion, semantic tokens, diagnostics, and go-to-definition
bind the exact source, lock, package, tool, target, and configuration snapshot.
They resolve:

- `domain`, `use`, imported names, traits, units, clauses, and profile fields
  to their exact package definitions;
- implementation bodies and language diagnostics through source maps to their
  exact language profile and semantic target;
- generated SDK symbols to their contract and projection receipt;
- commands and arguments to their versioned Developer Interface definitions;
  and
- declarations through normalized owner records, requirements, selections,
  Build, deployment, receipts, and causal facts where those stages exist.

Generated definition documents are read-only revision-bound views, usable
offline from the lock and retained artifacts. An unavailable or stale
definition fails explicitly. When source is malformed, tooling keeps the
lossless current bytes and diagnostics visible; it never presents the previous
valid semantic value as current.

Structured forms, tables, graphs, and diagrams are synchronized projections
over the same source transaction. They become read-only or unavailable when
they cannot faithfully cover the current source, while direct lossless text
editing remains available.

Canonical owners:
[System IDL](https://github.com/muijf/one/blob/main/systems/system-idl/AGENTS.md)
and [Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md).

Apply the boundary in [Build a typed service](/one/examples/service) and
[Define a semantic domain](/one/examples/semantic-domain).

Next: [set up editor tooling](/one/authoring/editor-tooling), then learn
[the `.one` source language](/one/authoring/source-language).