Domains and traits#

A semantic domain is a complete bounded language over One's fixed structural source format. It owns its vocabulary, rules, defaults, compatibility, normalization, and contributions to downstream owners. One-owned and organization-owned domains use the same contracts and lifecycle.

Foundation, inheritance, and composition#

Every domain has exactly one compatibility lineage rooted at one.semantic@1. extends inherits one complete language; use composes any number of additional packages without making them compatibility parents.

This excerpt uses the canonical ACME package source. Its owning conformance tests lower that source and execute its published trait rule and cases. Complete distribution and consumer acceptance remain separate lifecycle evidence.

one 1

semantic acme.compliance.package
    domain one.semantic.domain@1
    domain acme.compliance@1
        owner acme
        normalizer acme.compliance#Normalizer@1
        contribution acme.compliance#Declarations@1
        extends one.semantic@1
        trait Auditable@1
            site declaration
            contributes acme.compliance#Declarations@1
        kind control
            posture definition
            declaration control
                naming upper camel
                documentation "A named compliance control with one exact severity."
                completion "control ${1:Name}@1\n    severity ${2|low,medium,high|}"
                field severity
                    cardinality required
                    shape literal
                    literal low
                    literal medium
                    literal high
                    naming lower snake
                    documentation "Control enforcement severity."
                    completion "severity ${1|low,medium,high|}"
                definition Auditable
                    category trait
                    signature "trait Auditable"
                    documentation "Organization-owned auditability semantics."
                    completion "Auditable"
                    reference role trait

The documentation, naming, and completion entries above are the domain package's editor projection over the same declarations: they carry no extra meaning, and they stay in the owning domain package rather than in an application semantic item.

The semantic item's leading domain one.semantic.domain@1 clause is the kernel selector for the meta-domain; the later domain acme.compliance@1 block is that package's own definition of the domain it declares. They share the word domain but are distinguished by position and role: the first child is the selector, and every subsequent domain Name@lane block is a definition supplied by one.semantic.domain@1.

Use extends one.product@1 when the domain intentionally inherits the full product language. Extend one.semantic@1 and import narrow packages when it does not. There is no multiple inheritance or source-order conflict winner.

one.standard@1 is an optional explicit aggregation package, not an ambient prelude. A domain export preserves the original owner of every imported type, trait, unit, capability, and declaration kind.

Define a trait#

Trait packages use the one.trait@1 meta-domain. A trait definition owns:

• its owner-qualified identity and compatibility lane;
• the broad application-site category it may refine;
• typed arguments, defaults, bounds, conflicts, and repetition rules;
• semantic laws, normalization, and compatibility effects;
• required capabilities or prerequisite traits;
• possible owner contribution contracts; and
• documentation, diagnostics, formatting, and conformance obligations.

A broad category is only an upper bound. Declaring Key as a field trait does not make it applicable to every field.

Implement applicability coherently#

Inside the same domain definition, this exercised impl associates the already defined Auditable trait with the published Control declaration:

impl Auditable
    for acme.compliance#Control@1
    site declaration
    rule acme.compliance#AuditControl@1
    normalize true
    conformance acme.compliance#AuditControlSuite@1
        accept acme.compliance#Control@1
        reject acme.compliance#Other@1

The rule returns a Boolean contribution for its exact subject. The conformance suite declares accepted and rejected cases; executing it produces separate conformance evidence.

This is distinct from a top-level executable impl: the leading for marks a semantic trait implementation, while an executable claim uses realizes and using.

A package may publish a globally coherent implementation only when it owns the trait or the target nominal type/declaration kind. A package owning neither side publishes an explicit directional mapping that remains inert until one root selects it. Overlapping implementations fail unless their subject sets are provably disjoint; import order and “most specific” guesses never choose a winner.

Apply traits after the subject exists#

Postfix traits refine a completed type, field, member, declaration, operation, environment, or evidence subject. The following target example illustrates trait applications beyond the current Product implementation. Consult its owning support boundary for the exact accepted types and trait placements.

type UserName@1 = Text @Length(1..=128)
type Percentage@1 = Decimal @Value(0..=100)

record Upload@1
    tenant: TenantId @Scope
    id: Text @Length(1..=64) @Key
    chunks: List<Bytes> @Cardinality(1..=10_000)
    total_size: DataSize @Value(1B..=5GiB)

A field trait follows the field type. A declaration-wide invariant appears after every member it references. Trait applications form a canonical set, not an order-sensitive decorator pipeline.

Use precise traits: numeric value, text length, and collection cardinality are different meanings. @Value, @Length, and @Cardinality are not aliases for one generic range annotation.

Every bare @Key field contributes to one logical primary key. Multiple key fields form a canonical composite identity without choosing physical index order. @Unique(name) represents an independent candidate key. @Scope identifies logical subject scope; it does not create a partition or grant.

Resolution and normalization#

Strict checking:

1. resolves the trait through the primary domain or prior import;
2. constructs the exact completed subject descriptor;
3. finds matching implementations in the selected package closure;
4. rejects zero matches or non-identical multiple matches;
5. validates arguments, prerequisites, conflicts, and repetition;
6. runs the exact declarative rule or capability-empty normalizer;
7. asks every destination owner to validate proposed contributions; and
8. retains a receipt naming every definition, implementation, input, proof, contribution, and revision.

A custom normalizer receives only the bounded subject, arguments, exact package dependencies, and deterministic budget. It has no filesystem, network, clock, entropy, credentials, source-write access, provider selection, or authority, and it cannot mint trusted IR.

Unknown traits, unsupported subjects, ambiguity, invalid arguments, normalizer failure, and rejected owner contributions are semantic errors. Tooling retains and explains the source; it never discards a trait as metadata.

Publish and consume a domain#

The domain follows the ordinary lifecycle: check its schema and closure, build or select its normalizer, run domain and trait conformance, publish the exact package and evidence, lock it in a consumer, then select it as that semantic item's primary domain.

Publishing proves no application behavior and activates no consumer. The lock selects exact package, export, trait implementation, normalizer, definition, and compatibility revisions.

Next: author a product or follow define a semantic domain.