Task Recipes

This page answers: I have a specific modeling job to do — what are the steps?

Recipes are minimal: enough to get started, with cross-links to the chapter or RFD that explains the why.

I want to declare a new concept

1. Pick the metatype from your foundational-ontology package (most commonly UFO’s kind, subkind, role, phase, etc.).
2. Decide whether it specializes an existing concept and what its world assumption is.
3. Add where clauses for structural constraints (RFD-0018).
4. Make it pub if downstream packages should use it.

use ufo::prelude::*;
use std::math::Nat;

pub kind Person <: Agent
  where {
    age >= 0,
  }

See ch02-02.

I want to declare a relation between concepts

1. Decide endpoints (source and target concepts).
2. If it’s a recognized algebraic shape (transitive, symmetric, …), add the matching decorator.
3. If it has metarel semantics (mediation, externally-dependent), use :: <Metarel>.
4. Add cardinality constraints if needed.

@[transitive]
pub rel ancestor_of(a: Person, b: Person)

pub rel mediates(c: Commitment, p: Person) :: Mediation {
  cardinality: 1..1,
}

See ch02-03, RFD-0018.

I want to write a derivation rule

1. Identify the head — what fact is being derived.
2. Identify the body — what facts must hold for the head to follow.
3. Write pub derive head(args) :- body_atoms.
4. If the rule is meant to apply only when no override fires, leave it pub derive (defeasible). If it’s an unconditional theorem, use pub strict.
5. Add @[theorem] if the rule should be machine-verified.

pub derive adult(P) :- Person(P), age(P, A), A >= 18

Multi-head disjunction: write multiple rules with the same head and consistent strength.

See ch02-04, RFD-0007.

I want to retrieve facts by pattern

1. Write a query declaration with a Prolog-style :- body.
2. Project the result with => head_expression.

query adults() :-
  Person(P),
  age(P, A),
  A >= 18,
  => P

Every result carries why-provenance. See ch02-05, RFD-0007.

I want to apply a state transition

1. Write a mutation declaration with require (preconditions), do (assignments), optional retract (negative facts), optional emit (events), return (response).
2. The mutation will record its transition trace as provenance.

mutation hire(o: Organization, p: Person) {
  require { not works_at(p, _) }
  do { works_at(p, o); }
  emit { Hiring(o, p) }
  return p;
}

See ch02-05.

I want a calculation that returns a value

1. Pick the compute form (see decision-guides.md#which-compute-form).
2. Form 1 for one-shot, Form 2 for multi-step tier-bounded, Form 3 for native FFI.

// Form 1
compute gain(s: Sale) -> Money = s.proceeds - s.basis

// Form 2
compute classified_gain(s: Sale) {
  input { s: Sale }
  out { kind: String, amount: Money }
  ensure { s.proceeds >= 0 }
  body {
    let amount = s.proceeds - s.basis;
    let kind = if amount > 0 { "gain" } else if amount < 0 { "loss" } else { "wash" };
    { kind: kind, amount: amount }
  }
}

See ch02-05, RFD-0006.

I want to write a test

1. Use test <name> { ... }.
2. Set up state with assertions or with a fixture { ... } block.
3. Use expect to assert specific diagnostics or values.
4. Mark with #[unproven] or #[assumed] if appropriate.

test adult_classification {
  fixture {
    assert Person(alice);
    assert age(alice, 25);
  }
  expect { result adult(alice) at //~ check }
}  //~ check

See ch03-03, RFD-0008.

I want to model a recurring shape (correlative pair, part-whole, etc.)

Use a pattern. Either reach for a bespoke surface form (correlative_pair, part_whole) or write pub pattern <name> { ... } and instantiate with use pattern <name><types> as <instance>.

See ch03-01, RFD-0019.

I want to escalate beyond the default tier

1. Identify which tier you need (see decision-guides.md#when-to-escalate-tier).
2. Add #dec(<tier>) at module / block / declaration scope.
3. For full FOL, wrap the relevant block in unsafe logic { ... }.

#dec(tier:expressive)

pub derive complex_classification(X) :- ...

See tier-selection.md, ch05-03, RFD-0004.

I want to include a foundational ontology

1. Add the package to your ox.toml [dependencies].
2. use the foundational ontology’s prelude in your modules.
3. Refer to its metatypes by name.

# ox.toml
[dependencies]
ufo = "0.3.0"

use ufo::prelude::*;

pub kind Person <: Agent { ... }

See ch04-01, RFD-0014.

I want to render a diagram

1. Add a diagram block.
2. Specify which concepts/relations to include and a layout algorithm.

diagram TaxRoles {
  concepts { Person, Taxpayer, Withholding_Agent }
  relations { works_at, withholds_from }
  layout: sugiyama;
}

See ch03-04, RFD-0026.

I see an OE#### error and don’t know what it means

1. Run ox explain OE#### for the canonical long-form explanation.
2. Cross-reference error-recovery.md for common diagnostics with action hints.
3. Full reference: Appendix C.

See also

• Quick reference — syntax for every form.
• Decision guides — picking between alternatives.
• Anti-patterns — what to avoid.
• Idioms — what works well.