# Build complete systems through shared semantics

One is a System-IDL-first, Rust-implemented glass-box platform for declaring,
building, shipping, and operating complete systems. It gives independently
owned semantic domains and polyglot implementations one inspectable path:

```text
declare -> check -> test -> invoke -> plan -> build -> apply -> inspect
```

One unifies languages at the level of meaning. It does not pretend that Rust,
native One, Python, TypeScript, SQL, WebAssembly, a browser, and a remote
service have the same syntax, type system, runtime, failure model, or cost.
Rust is the canonical platform implementation and first SDK language; native
One is the coherent first-class executable language inside `.one`.

> **Product architecture:** This site explains the current end-product
> contract. Implemented support is established by each owning package's public
> API, README, and tests. Unavailable stages return typed unsupported,
> unsatisfied, or missing-evidence results.

## One file format, isolated language roles

A `.one` file is a bounded source envelope. It can contain:

- non-executable System IDL semantic documents;
- native executable One sections;
- isolated Rust, Python, TypeScript, SQL, or other admitted source sections.

The semantic sections own meaning and intent. Executable sections are untrusted
implementation source. Sharing a file does not create shared lexical scope,
imports, bindings, capabilities, or authority.

```one
one 1

semantic HelloContract {
    domain contracts
    namespace example.hello

    # bounded schemas and operation contracts
}

semantic HelloImplementation {
    domain implementation
    namespace example.hello

    implementation HelloServiceOne version 1 {
        realizes: example.hello#HelloService@1
        source: code HelloService
        profile: one.implementation-language.one#SafeAsync@1
    }
}

code HelloService language one 1 <<ONE
// isolated native-One implementation source
ONE
```

The envelope syntax is the intended product form. Native-One body syntax and
profiles remain illustrative until their owning implementation and tests
exist.

## What stays visible

Every meaningful step retains its owner and explanation:

| Concern | One keeps explicit |
| --- | --- |
| Meaning | semantic domain, declaration identity, exact revision, defaults, mappings |
| Implementation | source language, implementation profile, source closure, analysis evidence |
| Realization | provider, topology, target, conversion, artifact, conformance |
| Authority | requirement, approval, grant, runtime token, host enforcement |
| Effects | intent, dispatch, receipt, unknown outcome, reconciliation, compensation |
| Operations | observation, causal fact, plan, action, cost, provenance |

Generated clients, bindings, manifests, indexes, and documentation are
disposable projections. Their source contract and projection receipt remain
inspectable.

## One does not require one runtime

An application can use static local calls, processes, WebAssembly components,
remote services, Kubernetes, GitOps, embedded reconciliation, or a persistent
One controller. Crossing a boundary makes serialization, authorization,
deadlines, cancellation, retries, partial failure, backpressure, and cost
explicit.

Providers and adapters remain removable. A contract never depends on a
particular provider, and package presence never selects an implementation.

## Custom meaning is first-class

Organizations can publish their own semantic domains in their own namespaces.
They use the same bounded System IDL envelope and Contracts-owned
meta-contracts without translating their meaning into a `one.*` identity.

Two owners interoperate only through an explicit directional mapping whose
losses and proof path are visible. A custom domain can remain independently
checkable, distributable, and realizable.

## Continue

- Follow the [end-product walkthrough](/one/start/quickstart).
- Learn [how One lowers meaning into evidence](/one/start/how-one-works).
- Understand the [`.one` source format](/one/language/one-files).
- See the complete [architecture map](/one/reference/architecture).

Canonical architecture:
[repository contract](https://github.com/muijf/one/blob/main/AGENTS.md).