one.product@1 is One's concise omission-first language for complete product
meaning. Its declaration heads are ordinary domain exports, not parser
keywords. Other domains may inherit the whole language or expose a different
vocabulary through the same .one envelope.
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
@Invariant(total == sum(items[*].unit_price * items[*].quantity))
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
service Orders@1
query get
input tenant: TenantId
input id: OrderId
returns Order
faults GetOrderFault
command place
input request: PlaceOrder
returns Order
faults PlaceOrderFault
Queries and commands 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.
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
workflow FulfilOrder@1
input order: Order
returns Shipment
reservation = Inventory.reserve(order)
payment = Billing.capture(order)
compensate reservation
with Inventory.release(reservation)
if payment is domain_fault
shipment = Shipping.create(order, reservation)
return shipment
recovery BillingCaptureRecovery@1
operation: Billing.capture
correlation: Billing.capture.order_id
observe: Billing.lookup
A workflow preserves exact version, steps, nondeterministic inputs, effects, outcomes, timers, approvals, checkpoints, compensation, and reconciliation. Compensation is a new effect, not erased history. Recovery definitions explain how to resolve an uncertain dispatch without repeating it blindly.
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: "/v1"
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.