.uc
Use case pattern
Subjects, actors and successions
No in-tree backend — the artifact is validated and committed, not consumed.
SysML-v2-style use case patterns: subjects, actors, messages, successions and realizes links.
Why it exists
What .uc is for
A .uc file declares use cases in the SysML v2 pattern: a subject — the classifier whose behaviour is specified — the actors participating, the messages exchanged between anchored points of their behaviour, the successions that order it, and the domain service operations the use case realizes.
One abstraction note matters: an occurrence is a scenario-local lifetime point of one participant, not an .evt event. Imported event contracts enter a use case only as message payload types. The surface imports four buckets — raw .mox domains plus pre-compiled .ddd, .actor and .evt artifacts — and cross-checks the scenario against each of them.
Vocabulary
What it models
The concepts .uc declares, and what each one means to the compiler.
- usecase
- The declaration; its body is one scenario.
- subject
- The classifier under specification, typed by a domain class.
- actor
- A participant: a bare policy actor, or a domain-typed one. Only bare policy actors contribute capability coverage.
- occurrence
- A named lifetime point of a participant. Scenario-local — it is never an event.
- message
- An exchange
of <payload>between two anchored points: an occurrence, or the end of a performed step. - performed step
perform <name>: <operation> requires [ <capability> ]— a subject-performed step anchored to a design operation.- first … then …
- A succession ordering two points;
startanddoneare the bounds. - realizes
- Names the design service operation the use case realizes, cross-checked against the imported
.dddartifact. - requires
- Capability coverage, checked structurally against the permits the participating actors hold.
Source
A working example
Quoted from the example this page's artifact was compiled from — not a snippet written for the website.
Lines 45–62 of examples/support/support.uc, reproduced byte for byte, read from the file at build time:
usecase RaiseRefund {
subject Ticket: Ticket {
perform raise: raiseRefund requires [ RaiseRefund ];
}
actor Agent {
occurrence refundRequested;
occurrence refundEscalated;
}
message requestRefund of RefundRequested from Agent.refundRequested to Ticket.raise;
message escalate of RefundDecision from Ticket.raise to Agent.refundEscalated;
first start then requestRefund.source;
first requestRefund.source then requestRefund;
first requestRefund then raise;
first raise then escalate.source;
first escalate.source then escalate;
first escalate then done;
realizes support.TicketService.raiseRefund;
}The `RaiseRefund` scenario: a subject step bound to a design operation with a required capability, actor occurrences, two messages (one carrying an event payload), a succession chain from `start` to `done`, and the `realizes` link.
The whole file is CI-tested: pherolang check examples/ checks every surface in the tree, and the example harness compiles each one on every run. What you see above is the input to the artifact below.
Neighbours
How it relates to the other surfaces
Four imports, four checks: .mox types the participants and payloads, .ddd supplies the service operations realizes names, .actor supplies the actor principals and the permits requires: is checked against, and .evt supplies message payload types only. A scenario that needs both halves of a declared never_both pair is refused.
Commands
How to compile and validate
Three commands, one file. They run from the repository root against the example on this page.
pherolang check examples/support/support.uc
pherolang ir examples/support/support.uc -o site/data/artifacts/uc.json
pherolang artifact check site/data/artifacts/uc.jsoncheck parses, resolves, validates and type-checks the file and printsOK examples/support/support.uc. ir writes the artifact and prints nothing on success. artifact check then validates the serialized JSON on its own — no model, no import resolution, no compiler — and prints OK site/data/artifacts/uc.json.
Directories work too: pherolang check examples/ enters project mode and checks every supported surface under the tree, each file's imports resolving from the snapshot.
Artifact
What it produces
One versioned JSON artifact, emitted by the compiler and consumed by whatever reads this surface.
One UseCaseModel: each use case with its subject, participants, occurrences, messages, successions and realized operations.
The artifact is site/data/artifacts/uc.json, and it is committed here exactly as the released pherolang binary emits it. Its top-level shape:
useCases6 entries
Provenance
- formatVersion = 2
- The compatibility gate. A reader accepts this number or refuses the file.
- pheroVersion — not present
- This standalone surface artifact is versioned on its own
formatVersion; only the domain model artifact carries the compiler-version stamp. - 9,024 bytes
- 388 lines, two-space indented, in the file's own key order.
The compiled artifact
The first 16 of 388 lines, verbatim — the exact bytes pherolang ir writes, not a hand-written sample. The slice stops at a JSON boundary; the ellipsis marker is outside the JSON, and the full file is site/data/artifacts/uc.json.
artifacts/uc.json · lines 1–16
{
"formatVersion": 2,
"useCases": [
{
"name": "TrackRefund",
"description": "Iteration 1: a subject and one bare policy actor — nothing else.",
"subject": {
"name": "Ticket",
"typeName": "nz.example.support.Ticket"
},
"actors": [
{
"name": "Agent"
}
]
},… 372 more lines in site/data/artifacts/uc.json
Regenerate it from the repository root — the second command validates the serialized bytes with no compiler in the loop:
pherolang ir examples/support/support.uc -o site/data/artifacts/uc.json
pherolang artifact check site/data/artifacts/uc.jsonThe whole data directory is regenerated by node scripts/sync-model.mjs (run from site/) with the released binary; CI fails on a one-byte difference.
Reference
Documentation
The normative reference for this surface, rendered from the repository's own documentation.
docs.pherolang.com
Use case pattern reference
Generated from docs/USECASES.md in the repository. The page above summarises it; the reference is normative.