§ 3 · Write
Cases and time
On this page
- 3.1 Supplying a case
- 3.2 Assumptions and scenario evaluation
- 3.3 Record shape
- 3.4 Valid time and record time
- 3.5 Evidence after known-at does not count
- 3.6 Completions are the model boundary
- 3.7 Money and structured values
- 3.8 Authority grants and duty events
- 3.9 Annotated example: court selects I2
- 3.10 Checklist
This guide explains how to supply a case record to Fidryn. Fidryn is a research interpreter for legal instruments. It is not legal advice, not an operative filing system, and not a statement of any jurisdiction's law. The JSON you write is a fixture for evaluation, not a court record.
A case is a fidryn.case-record/v0.1 document. The interchange schema is
schemas/case-record-v0.1.json. Wire
names are camelCase except where a nested type keeps its Rust field names
(determinations use recorded_at).
Required properties are schema and admissibleCompletions. Everything
else may be omitted and defaults to empty. The published schema lists
schema, module, facts, evidence, determinations,
interpretations, decisions, closures, outsideScope, and
admissibleCompletions. The interpreter also reads events and
assumptions when present; those fields are not yet in
schemas/case-record-v0.1.json
(additionalProperties is false there). Treat that published schema lag
as an evidence gap in
implementation-status, not as CLI behavior.
3.1 Supplying a case #
Pass a JSON file to fidryn run or fidryn explore:
fidryn run PATH --query NAME --case RECORD.json --valid-at TIME --known-at TIME \
[--arg KEY=VALUE] [--scenario]
fidryn explore PATH --query NAME --case RECORD.json --bounds BOUNDS.json \
--valid-at TIME --known-at TIMETIME is ISO 8601 / RFC 3339 with a Z suffix or a numeric offset
(2033-01-01T00:00:00Z, 2033-01-01T00:00:00+00:00). Equal instants
canonicalize to UTC. run never chooses a missing completion. --arg KEY=VALUE writes case.facts["KEY"]. --scenario evaluates with
case.assumptions as an overlay. explore --bounds merges extra
declared domains into admissibleCompletions. Successful run /
explore stdout is fidryn.evaluation-report/v0.1.
See CLI, the language grammar, and Outcomes.
3.2 Assumptions and scenario evaluation #
Assumption rows are { "id": "...", "payload": ... }. They are overlay
hypotheses, not operative ledger events.
- CLI
runwithout--scenariois operative:case.assumptionsare ignored for evaluation. - CLI
run --scenarioapplies those rows as a scenario overlay and labels the reportexecutionMode: scenario(assumptions are serialized on the evaluation-report envelope). - Mill
/api/runand/api/explorehave no--scenarioflag; a nonemptyassumptionsarray selects the scenario path automatically.
The published interchange schema
schemas/case-record-v0.1.json does
not yet list events or assumptions (additionalProperties is false).
The interpreter still reads both when present. Treat that as schema lag /
an implementation extension documented in
implementation-status, not as proof that the
fields are invalid at runtime.
3.3 Record shape #
| Field | Meaning |
|---|---|
schema | Must be the string fidryn.case-record/v0.1. |
module | Optional module identity (Name@version). The outcome envelope uses the compiled module, not this string, as sourceSnapshot. |
facts | Named values already treated as given. Bare JSON booleans, integers, and strings are accepted. |
evidence | Observed records. Each item has schema, value, and observedAt. |
determinations | Competent judgments already on file. Nested fields are issue, protocol, established, decider, and optional recorded_at. |
interpretations | Selected alternative per interpretation family ("SuccessorEligibility": "I2"). |
decisions | Selected option per choice protocol. |
closures | Closed-world flags (domain, closed). Absence is not a determinate negative unless the domain is closed. |
admissibleCompletions | The declared finite model. This is the model boundary, not a hint. |
outsideScope | Named exclusions. The outcome envelope unions these with the module's outside_scope. |
events | Optional ledger rows (kind, validTime, recordTime, payload). |
assumptions | Optional overlay hypotheses (id, payload). Not operative case state. CLI run --scenario applies them; mill /api/run and /api/explore treat a nonempty list as scenario mode. Default run without --scenario leaves them unused. |
admissibleCompletions has three maps:
"admissibleCompletions": {
"interpretations": {
"SuccessorEligibility": ["I1", "I2"]
},
"evidence": {
"SecondConcurringCertificate": {
"responses": ["absent", "present_prospective"],
"effectOnValidTime": "unchanged_if_after_query_valid_time"
}
},
"choices": {
"DistributionProtocol": ["hold", "distribute"]
}
}interpretations maps a family name to the alternatives the instrument
still admits. evidence maps a schema name to a finite response list
and an optional effectOnValidTime. choices maps a protocol name to
the options a decision-maker may still pick.
That object is the model. An omitted family is not silently filled in
later. An empty declared list for a named family is not a vacuous
determinate world: explore treats it as an empty completion set
(inconsistent), even if interpretations already records a selection.
A recorded alternative that is not in the declared list is outside
competence, not a new world.
3.4 Valid time and record time #
Fidryn is bitemporal. Every evaluation has two clocks.
--valid-at is valid time: the instant on the legal timeline you are
asking about (when occupancy, a deadline, or a status is supposed to
hold). --known-at is record time: the instant of the file you are
willing to treat as known. Occupancy and similar ledgers must contain
the valid instant and must have been recorded no later than record time.
These clocks are independent. You can ask what the office was on 2026-08-23 using only records known on that day, or you can ask the same valid-time question using a later known-at that includes subsequent filings.
The outcome envelope repeats the pair as asOf.validTime and
asOf.recordTime.
3.5 Evidence after known-at does not count #
Each evidence item carries observedAt. Observe matches schema, the
issue's subject when the value designates one, and observedAt <= --known-at. A certificate dated after known-at is invisible to that
query. It does not become a determinate negative; the query still
suspends if the remaining known record is incomplete.
The same cutoff applies to duty and institutional events: recordTime
after known-at is not admitted.
Determinations match protocol and issue. established: false is a
negative determination from a competent authority, not
outsideCompetence. A determination for Alice does not discharge a
judgment about Bob.
3.6 Completions are the model boundary #
run evaluates the case you gave. If an interpretation, choice, or
judgment is required and missing, the outcome is suspended with a
needInterpretation, needChoice, or needJudgment request. run
does not pick I1 because it is listed first.
explore searches the declared completions. Recorded selections
constrain that search: a case that already records
SuccessorEligibility: I2 is not re-opened onto I1. Declared evidence
responses such as absent versus present_prospective are hypothetical
worlds for explore, not facts invented by run.
Three different empty-looking objects are not the same:
"admissibleCompletions": {}declares no open families. A query that does not need an interpretation can still be determinate."interpretations": {}on the case means no alternative has been selected yet. If the query needs one,runsuspends."admissibleCompletions": { "interpretations": { "Family": [] } }declares a family whose admissible set is empty. That is not a determinate answer by vacuity. Explore reportsinconsistentwith coreempty completion set. A recorded selection cannot reopen that empty domain.
Interpretations you record must be members of the declared domain for
that family. I2 is lawful only when I2 appears in
admissibleCompletions.interpretations.SuccessorEligibility. An
off-list selection is outsideCompetence (recorded interpretation is not in the admissible set / inadmissible interpretation). The same
rule applies to decisions versus choices.
3.7 Money and structured values #
Case JSON accepts bare literals for booleans, integers, and strings. Decimals and other runtime values must be tagged so they do not alias those literals.
{ "kind": "decimal", "data": "1.25" }is money-as-decimal. The bare string "1.25" is a string. A JSON
number that is not an integer may decode as decimal, but do not rely on
that for amounts you care about: write the tagged form.
{ "kind": "bool", "data": false }is the boolean false.
{ "kind": "record", "data": { "kind": "bool", "data": false } }is a user record whose fields happen to be named kind and data.
Without the record wrapper, {"kind":"bool","data":false} is always
boolean, so you cannot store a complaint-shaped object that uses those
field names as a tagged bool. Unknown kind tags (for example
{"kind":"Complaint","id":"1"}) decode as a map, not as a bool.
Other tagged forms you may need:
{ "kind": "entity", "data": "Alice" }
{ "kind": "instant", "data": "2026-08-23T12:00:00Z" }
{ "kind": "prop", "data": { "predicate": "Incapacitated", "arguments": [] } }A bare "Alice" is a string, not an entity. A proposition is never a
boolean; see Outcomes.
3.8 Authority grants and duty events #
Institutional events do not commit performance just because they appear
in JSON. Events with kind duty, authority, or institutional are
admitted only when an AuthorityGrant covers the action at
recordTime. Assumptions are explicit: kind assumption skips that
gate.
Grants may be evidence:
{
"schema": "AuthorityGrant",
"value": { "action": "perform" },
"observedAt": "2026-01-01T00:00:00Z"
}or a fact named authority_grants. A duty event whose payload is
Performed / action: "perform" without a covering grant is dropped
from the duty machine. It does not turn duty_status into Performed.
kind evidence rows are copied onto the record ledger at
recordTime. Other documented kinds include correction and
retraction. Events are append-only in the interpreter; they do not
rewrite earlier rows.
A typical duty event:
{
"kind": "duty",
"validTime": { "start": "NegInf", "end": "PosInf" },
"recordTime": "2026-01-01T00:00:00Z",
"payload": {
"kind": "ctor",
"data": { "name": "Performed", "fields": {} }
}
}validTime is an interval (start / end are NegInf, PosInf,
Inclusive of an instant, or Exclusive of an instant). recordTime
is a single RFC 3339 instant.
3.9 Annotated example: court selects I2 #
The fixture
examples/trust/cases/court-selects-i2.json
is a complete case for Examples.BryanRevocableTrust. The module
declares interpretation family SuccessorEligibility with alternatives
I1 (Alice and Bob both eligible) and I2 (only Bob eligible). Two
physician certificates and an occupancy record are on file. A court (or
other controlling selector) has already chosen I2.
{
"schema": "fidryn.case-record/v0.1",
"module": "Examples.BryanRevocableTrust@0.1.0",
"facts": {
"alice_accepted": true,
"bob_accepted": true
},
"evidence": [
{
"schema": "OccupancyRecord",
"value": "Bryan",
"observedAt": "2026-08-23T12:00:00Z"
},
{
"schema": "PhysicianCertificate",
"value": "certificate-1",
"observedAt": "2026-08-23T12:00:00Z"
},
{
"schema": "PhysicianCertificate",
"value": "certificate-2",
"observedAt": "2026-08-23T12:00:00Z"
}
],
"interpretations": {
"SuccessorEligibility": "I2"
},
"admissibleCompletions": {
"interpretations": {
"SuccessorEligibility": ["I1", "I2"]
}
}
}What each part is doing:
schemaidentifies the interchange format. Reject anything else.modulenames the fixture this record is meant to accompany. Compileexamples/trust/bryan-revocable-trust.fr; do not treat this string as a source-snapshot digest.facts.alice_acceptedandfacts.bob_acceptedrecord that both nominees have accepted office. They are booleans, not propositions.OccupancyRecordwith valueBryanis who occupiesTrusteeOf(BRT)at the observation instant. Unique-occupant queries need this (or an equivalent ledger row). Two occupants for one office areinconsistent.- Two
PhysicianCertificaterows, both observed at2026-08-23T12:00:00Z, are the concurring record the instrument's incapacity judgment expects. If--known-atis earlier than that instant, neither certificate counts. interpretations.SuccessorEligibilityisI2, which is a member of the declared domain["I1", "I2"]. That selection is already on the case, sorundoes not suspend forneedInterpretation, andexploredoes not also try I1.admissibleCompletionsis nonempty. The still-admissible worlds are exactly those two named alternatives, of which one has been chosen. Contrasttwo-certificates-open-eligibility.json, which has the same certificates and domain but no recorded interpretation:runstays suspended,exploreis contingent between Alice and Bob.
Against acting_trustee with --valid-at / --known-at at or after
the observation times, both run and explore answer Bob. That
agreement is not a general guarantee; see Outcomes.
3.10 Checklist #
- Set
"schema": "fidryn.case-record/v0.1". - Declare every still-open family, evidence schema, and choice protocol
under
admissibleCompletions. Leave a family off the object only if it is not part of this model. - Put recorded interpretations and decisions in those declared lists.
- Timestamp evidence with
observedAtand choose--known-atso that later records do not leak into an earlier file. - Tag decimals. Do not store amounts as bare strings.
- Wrap user objects that need fields named
kindanddataas{ "kind": "record", "data": { ... } }. - Do not expect a
dutyevent to perform an obligation unless anAuthorityGrantcovers the action, or the event is an explicitassumption. - Treat
outsideScopeas part of the answer. The envelope will repeat it onmodelBoundary.
The modules, records, and examples here are research fixtures. They are not legal advice, not operative instruments, and not a complete statement of any jurisdiction’s law.