# Build a typed service

This recipe follows ParcelHub's checked order lookup contract, native One
implementation, generated Rust SDK, and ordinary lifecycle. The semantic and
native One excerpts mirror the current owning example; shortened request and
command forms remain illustrative end-product syntax.

## 1. Enter through one project

`one.one` establishes scope and selects the application source and exact lock:

```one
one 1

semantic parcelhub.one
    domain one.project@1
    project ParcelHub@1
        source ./one/contracts.one
        source ./one/application.one
        source ./one/system.one
        source ./one/orders_get.one
        source ./one/orders_place.one
        source ./one/orders_cancel.one
        lock ./one.lock
```

The entry point contains no operation or implementation body.

## 2. Declare the operation

The semantic source owns nominal values, results, faults, effects, and the
service boundary without choosing HTTP, a process, or a database:

```one
one 1

semantic parcelhub.orders
    domain one.contracts@1
    schema CustomerId@1 = Identifier
    schema OrderId@1 = Identifier

    struct OrderKey@1
        customer_id: CustomerId
        order_id: OrderId

    enum OrderStatus@1
        pending
        canceled

    struct OrderView@1
        customer_id: CustomerId
        order_id: OrderId
        status: OrderStatus

    fault OrdersGetFault@1
        not found

    operation Orders.Get@1
        accepts OrderKey
        returns OrderView
        faults OrdersGetFault
        effect read
        deadline 1s
        invocation direct
        requires one.data.state#Read@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )
        requires one.authority#ScopedStateRead@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )

    service Orders@1
        expose Orders.Get
```

`not_found` is a domain outcome. Denial, cancellation, timeout, provider
failure, and outcome unknown remain distinct outer dispositions.

## 3. Implement the exact claim

The implementation header claims one semantic target and one language profile.
Checking and conformance still decide whether the claim is eligible:

```one
impl parcelhub.implementation#OrdersGetOne@1
    realizes parcelhub.orders#Orders.Get@1
    using one.language.one#SafeAsync@1
    source
        use claim.requirements::state

        async Get(request: OrderKey) -> Result<OrderView, OrdersGetDomainFault> {
            match state::read(request, state) {
                some(stored) => ok(OrderView {
                    customer_id: request.customer_id,
                    order_id: request.order_id,
                    status: stored.status
                }),
                none => err(not_found)
            }
        }
```

The implementation receives only declared capabilities. It does not discover
a database, network, secret, clock, or provider from the environment.

## 4. Check, test, and invoke

```console
cargo test -p parcelhub --all-targets
cargo check -p parcelhub --no-default-features
one check --workspace systems/system-idl/examples/parcelhub --offline
```

```json
{
  "customer_id": "7",
  "order_id": "42"
}
```

The invocation result preserves the exact operation revision, implementation
claim, binding, principal, deadline, semantic result or fault, outer failure,
and evidence references.

## 5. Add a protocol only at the edge

An HTTP projection can map `Get` to `GET /orders/{order_id}`, but the route is
not the operation identity. A process-local caller can use the same operation
without HTTP, and changing protocol does not revise the service meaning.

## Executable evidence

The checked-in
[ParcelHub project](https://github.com/muijf/one/tree/main/systems/system-idl/examples/parcelhub)
owns the exact source, lock, generated SDK receipt, native One Get/Place/Cancel
implementations, Rust contract tests, reactive-query test, and Developer
Interface lifecycle evidence used by this recipe.

Next: [add governed persistent state](/one/examples/data-service) or
[ship the root](/one/examples/release).