End-product walkthrough#

This walkthrough shows the intended ordinary product path. It is design-oriented: use the repository's package READMEs for commands that are currently executable.

1. Create or adopt a project#

one init hello
cd hello

one init creates or adopts the initial reviewed one.lock. The lock records exact semantic and implementation-language dependencies. It does not activate code, choose a runtime provider, or grant authority.

2. Declare meaning#

Author bounded schemas and an operation contract in a .one semantic section:

one 1

domain contracts
namespace example.hello

record HelloRequest version 1 {
    name: Text<1..80>
}

record Greeting version 1 {
    message: Text<1..160>
}

operation SayHello version 1 {
    input: HelloRequest
    output: Greeting
    effect: pure
}

The exact grammar above is illustrative beyond the currently implemented authoring fragment. The important contract is bounded, owner-validated, non-executable meaning.

3. Associate an implementation#

The implementation claim names the contract, executable entry, and exact implementation-language profile. The body can be native One or another admitted language.

semantic Implementation {
    domain implementation
    namespace example.hello

    implementation SayHelloOne version 1 {
        realizes: example.hello#SayHello@1
        source: code SayHelloBody
        profile: one.implementation-language.one#SafeAsync@1
    }
}

code SayHelloBody language one 1 <<ONE
// implementation body governed by the selected profile
ONE

The section is inert until analysis validates its exact source closure and Composition makes the candidate visible to a selected root.

4. Check without executing#

one check project

Checking parses the bounded .one envelope, validates each semantic document through its exact domain package, and checks claimed source through its exact language/profile tooling. It does not execute the application, select a provider, write one.lock, or grant capabilities.

5. Test the owned contracts#

one test unit
one test conformance
one test simulate

Tests prove only the behavior they exercise. Provider conformance, effect recovery, replay, and integration evidence remain separate and owned.

6. Invoke or plan#

An exact operation that permits direct invocation can be called through any projection of the same identity:

one invoke example.hello#SayHello --json '{"name":"Ada"}'

An operation that requires planning produces an immutable plan:

one plan one.deployment#Deploy --environment production
one inspect plan:<digest> --explain

Friendly aliases are allowed only when the selected project lock resolves them unambiguously.

7. Build exact root artifacts#

one build --root hello --target wasm32-component

Build consumes the locked physical plan. It cannot reselect providers. The result records sources, toolchains, actions, dependencies, generated contract bindings, artifact digests, conformance evidence, and provenance.

The recommended first native-One realization is one typed contract function compiled into a WebAssembly component whose WIT ABI is a receipted projection of the exact One Contract Schema.

8. Apply the reviewed plan#

one apply plan:<digest>

Apply verifies the plan, approval, artifact, authority, and allowed refreshed observations. It journals and fences exact actions. It never replans, rebuilds, widens authority, or blindly repeats an unknown-outcome effect.

9. Inspect the proof path#

one inspect example.hello#SayHello --explain
one inspect artifact:<digest> --explain
one inspect plan:<digest> --explain

Inspection resolves exact owner-qualified subjects. It shows authored values, defaults, mappings, selected providers, capabilities, costs, artifacts, actions, and evidence without maintaining a second CLI-owned semantic model.

Next: how One works.