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 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 and Contracts.

Apply the boundary in Build a typed service and Define a semantic domain.

Next: set up editor tooling, then learn the .one source language.