Author a product#

This page illustrates the end-product surface targeted for one.product@1. Its examples include target syntax beyond the currently implemented package. Declaration heads are ordinary domain exports, not parser keywords. Other domains may inherit the language or expose a different vocabulary through the same .one envelope.

For supported declarations and restrictions, follow the normalizer's Product support boundary, which links its owning tests and canonical Order Review consumer. Package availability alone does not establish support for the examples below.

Declaration heads are domain-owned#

Every head below is an export of a selected semantic domain, not a universal parser keyword. The Status column distinguishes declarations the current one.product@1 or one.contracts@1 package implements from illustrative end-product target syntax. A head absent from the selected package fails with UnknownDeclaration; it is never guessed.

Two consequences follow. First, error is the Product fault head and fault the Contracts head; both accept unit variants only, so the payload form invalid_catalog_item(sku: Sku) below is illustrative target syntax. Second, operation identity is the dotted Namespace.Member@1 form used by expose; a bare operation Get@1 is not canonical.

workflow is demonstrated under one.contracts@1 (see Build a durable workflow); the other heads in that row remain illustrative Product target syntax.

One head per owner; vocabularies are not interchangeable#

Contracts and Product are separate owners with separate vocabularies. Each names the concept with its own head; the two are not synonyms of one language, and a source must use the head its selected domain supplies:

A head absent from the selected package fails with UnknownDeclaration; it is never substituted from the other package. The record/type/error heads used below are Product; a Contracts source writes struct/schema/fault and bounds with T(args) instead. The kernel role is fixed everywhere; only the word is domain-owned.

Define nominal values and faults#

type OrderId@1 = Text @Length(1..=64)

enum OrderStatus@1
    pending
    placed
    cancelled

record LineItem@1
    sku: Sku
    quantity: UInt @Value(1..=100)
    unit_price: Money

record Order@1
    tenant: TenantId @Key @Scope
    id: OrderId @Key
    items: List<LineItem> @Cardinality(1..=100)
    total: Money
    status: OrderStatus

error PlaceOrderFault@1
    duplicate
    invalid_catalog_item(sku: Sku)
    price_changed(expected: Money, actual: Money)

Types and declarations are nominal. Structurally identical records under different owner-qualified identities remain different. Faults are part of the operation contract and stay distinct from denial, timeout, cancellation, provider failure, defects, and unknown outcomes.

Declare operations and services#

A Product service declares operations as members. The intended end-product surface uses query and command members that state behavior directly:

service Orders@1
    query get
        input tenant: TenantId
        input id: OrderId
        returns Order
        faults GetOrderFault
        requires one.data.state#Read@1
            resource: parcelhub.orders
            scope: fields(customer_id, order_id)

    command place
        input request: PlaceOrder
        returns Order
        faults PlaceOrderFault

The currently demonstrated Product subset declares each member with operation and the same input, result, fault, effect, deadline, and capability clauses; the query/command form above is the target those members will generalize to:

service Orders@1
    operation get
        input OrderKey
        returns OrderView
        faults OrdersGetFault
        effect read
        deadline 1s
        requires one.data.state#Read@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )

    operation place
        input PlaceOrder
        returns Order
        faults OrdersPlaceFault
        effect irreversible
        idempotency operation(window: 24h)
        deadline 3s
        requires one.authority#ScopedStateWrite@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )

Contracts-owned operations use a different, currently demonstrated shape: a top-level dotted operation Namespace.Member@1 with accepts/returns, plus a service that exposes it:

operation Orders.Get@1
    accepts OrderKey
    returns OrderView
    faults OrdersGetFault
    effect read
    deadline 1s
    invocation direct

service Orders@1
    expose Orders.Get

Operations state semantic behavior, inputs, outputs, faults, effects, authority, idempotency, deadlines, and recovery where applicable. They do not choose HTTP, messaging, a process boundary, a provider, or placement. See operations and outcomes for the clause reference and the target/demonstrated split, contracts and components for placement, and the failure model for the outcome vocabulary.

Declare state and events#

state OrdersState@1
    stores Order
    consistency serializable
    durability durable

event OrderPlaced@1(Order)
event OrderCancelled@1(Order)

State declares logical keys, scope, transactions, queries, change behavior, retention, evolution, continuity, and recovery. It does not name tables, indexes, partitions, SQL, storage files, or database handles. An event records owned meaning; publication semantics and delivery guarantees remain explicit Communication contracts.

Coordinate durable work#

A workflow declares durable coordination as a non-executable, versioned graph of activities; it is not a program. An activity lists only the outcome dispositions it overrides; every outcome it omits defaults to the safe terminal disposition, so the normalized graph remains exhaustive. Deterministic decision code lives in a separate implementation body:

workflow FulfilOrder@1
    accepts PlaceOrderRequest
    returns Shipment
    concurrency "orders/fulfilment"
    retention days 30
    evidence order.request parcelhub.orders#PlaceOrderRequest@1
    evidence order.shipment parcelhub.shipping#Shipment@1

    activity reserve_inventory
        operation parcelhub.inventory#Inventory.Reserve@1
        effect replay safe
        maximum attempts 3
        owns cancellation true

    activity capture_payment
        operation parcelhub.billing#Billing.Capture@1
        effect irreversible
        maximum attempts 1
        owns cancellation false

    activity create_shipment
        operation parcelhub.shipping#Shipping.CreateShipment@1
        effect irreversible
        maximum attempts 1
        owns cancellation false

The deterministic decision code that chooses among those outcomes is an isolated impl body — for example the Rust match in Build a durable workflow. It never reads the wall clock, network, filesystem, entropy, or secrets directly; those arrive as recorded activity results, timers, signals, and human decisions.

A workflow preserves exact version, steps, nondeterministic inputs, effects, outcomes, timers, approvals, checkpoints, compensation, and reconciliation. Compensation is a new effect, not erased history. A recovery definition explains how to resolve an uncertain dispatch without repeating it blindly:

# Illustrative target syntax; not a demonstrated Contracts head.
recovery BillingCaptureRecovery@1
    operation Billing.capture
    correlation Billing.capture.order_id
    observe Billing.lookup

Jobs, schedules, streams, human tasks, and agents use the same explicit completion, cancellation, budget, authority, and evidence model. An agent's model output is untrusted proposal data; tools are typed operations rather than credentials.

Compose components, roots, and boundaries#

component OrdersApi@1 realizes Orders
component OrderWorkers@1 realizes FulfilOrder

boundary PublicOrdersHttp@1
    projects Json(Orders)
    authentication CommercePolicy
    base_path "/commerce"

The system/root declaration lives in its own owner-governed semantic item:

one 1

semantic acme.system
    domain one.system@1

    component CommerceApi@1
        owner acme.principal#Commerce@1
        provide service acme.orders#Orders@1
        require one.deployment.local.release#Apply@1
        require one.history.durable#Append@1

    system Commerce@1
        root commerce_api
            include CommerceApi
            build development
            build release
            build reproducible

Components state uses and realization obligations without choosing local, process, Wasm, or remote topology. A boundary deliberately projects an owned contract to HTTP, messaging, a client, an SDK, or another physical form and retains every conversion and loss. Each application, worker, migration, operator, client, and tool root receives an independent closure.

State policy, privacy, and tenancy#

policy CommercePolicy@1
    profile TenantRoles
    allow
        roles
            owner
            operator
        operations
            Orders.get
            Orders.place

privacy CustomerOrderPrivacy@1
    classify Order.customer as personal
    purpose order_fulfilment
    retain Order for 7y because legal_obligation
    erase lineage_from Order.customer on valid_request
    export_within 30d

Policies declare requirements and decisions; they do not issue grants. Privacy, tenancy, retention, residency, erasure, export, and audit obligations remain explicit product meaning and flow into Planning, Authority, Data, History, and observation requirements.

Define environments and objectives#

environment Local@1
    profile LocalDevelopment
    expose PublicOrdersHttp at http("127.0.0.1:8080")

environment Production@1
    profile EuProduction
    expose PublicOrdersHttp at https("api.acme.example")
    monthly_cost <= 5_000USD
    availability >= 99.95%
    release_requires BillingUnknownOutcome

Environments contain portable desired state, quality, cost, assurance, placement, observation, and release requirements. They do not contain secret bytes, issued grants, live provider handles, or mutable observations. Profiles package repeated owner meaning but never hide weaker guarantees or choose a provider instance.

Author tests, simulations, and release gates#

simulation BillingUnknownOutcome@1
    interrupt Billing.capture after dispatch before acknowledgement
    then Billing.lookup returns committed
    assert FulfilOrder does_not_redispatch Billing.capture

Tests and simulations bind exact source, lock, fixtures, time, entropy, scheduler, faults, provider responses, assumptions, and expected owner results. They prove only their declared scope. Release gates may require conformance, security, accessibility, performance, recovery, and observation evidence for the exact release.

Keep omission honest#

Omission means the selected exact domain rule supplies a deterministic default or derivation. It never means “whatever the provider does.” Inference can prove consequences and add conservative requirements; it cannot invent business identity, consent, legal basis, provider selection, authority, accepted loss, or absence outside a proven boundary.

Next: learn how product declarations lower into contracts and components.