Fidryn

Docs Language

§ 2 · Write

The Fidryn language

On this page
  1. 2.1 Surface inventory (status-qualified)
  2. 2.2 Module header
  3. 2.3 Sources and digests
  4. 2.4 Imports
  5. 2.5 Entities, propositions, and offices
  6. 2.6 Record and evidence types
  7. 2.7 Observations
  8. 2.8 Queries, goals, and effects
  9. 2.9 Automatic versus judgment
  10. 2.10 Require, return, and sequential evaluation
  11. 2.11 Calc, conditionals, money, and durations
  12. 2.12 Rules
  13. 2.13 Interpretation families
  14. 2.14 Nominations
  15. 2.15 Powers, legal acts, clauses, and conflict doctrines
  16. 2.16 Duties
  17. 2.17 Transactions and quantifiers
  18. 2.18 Scenarios (in-module)
  19. 2.19 Verify
  20. 2.20 What the language will not do

Read this as a map of the constructs you will see in .fr files, then open the fixtures and check them. For build, check, and the first run, start with Getting started.

Fidryn (FID-rin) is a language for legal instruments: precise where law is mechanical, explicit where judgment enters. This repository is the v0.1 research interpreter. Example modules are fixtures. They are not legal advice, not operative instruments, and not a complete statement of any jurisdiction's law.

The grammar is closed: unknown body fields are parse errors. Copy from an existing .fr file when you are unsure a spelling parses. The reference is grammar.ebnf.

2.1 Surface inventory (status-qualified) #

The grammar (grammar.ebnf) is broader than this map. Use the table as a honesty check; open a fixture for the full field list. v0.1 support is parsed / checked / executed only where noted — see implementation-status.

ConstructFixture exampleStatus note
import (+ digest / alias)examples/trust/bryan-revocable-trust.frParsed/checked; hex digests authenticate under CLI check_path
record_type / evidence_typeFOIA / trust fixturesParsed/checked; used as named evidence schemas
observationLLC / state homestead modulesParsed/checked; Observe matches schema + known-at
scenarioall 50 examples/states/ modulesIn-module overlay fixtures; not JSON cases; not silent run defaults
Evaluate / UniqueOccupant / RunDecision / StatusOftrust, late-payment, LLCExecuted query plans
EvaluateClauseexamples/prenup/ava-noah.frExecuted clause-plan queries
power / legal_act / clausetrust, FOIA, prenupParsed/checked; specialized paths, not a general act engine
conflict_doctrineprenup, minimum-wageParsed; conflict outcomes/requests when staged effects disagree
transactiontests/programs/transaction-atomic.frPartial; not a full commit engine
for_all / existsstatus + grammarFinite declared domains only; open domains suspend; no open-world proofs
fngrammar / statusLimited/partial; no current example declaration
Module type parametersstatusType-name substitution only; no cross-file value-parameter calculus

2.2 Module header #

Every file is one module. The header names the instrument, the dated slice it encodes, and what it refuses to claim.

.fr
module Programs.LatePayment version "0.1.0" {
    jurisdiction Test
    source_snapshot "2026-09-17-late-payment"
    effective_at 2026-09-17
    recorded_at 2026-09-17T12:00:00Z

    outside_scope { complete_instruments }

    // queries, duties, and interpretation families follow
}

jurisdiction is a name, not a choice of engine. source_snapshot is the dated slice this file encodes. effective_at is a date. recorded_at is a date-time (Z or a numeric offset). outside_scope is a set of named exclusions; those names reappear on the outcome's modelBoundary.

The trust fixture also declares a source manifest, resolved relative to the module file:

.fr
source_manifest "sources/ma-trust-fixture.manifest.json"

A declared path that is missing or malformed is a diagnostic. Modules that omit a manifest get an empty default. CLI check / run of a path can byte-authenticate artifacts against files next to the module. Pasted source in the Mill does not.

2.3 Sources and digests #

A source { } block names an artifact the module is encoding.

.fr
source FinalPayStatute {
    kind statute
    authority CaliforniaLegislature
    citation "Cal. Lab. Code §§ 201-203"
    artifact "sources/ca-lab-201-203.txt"
    digest fixture
    effective [2026-09-17, +inf)
}

digest fixture is a fixture profile, not a hash of the file. It is not byte-verified authentication. A 32- or 64-digit hex digest is blake3 of the artifact bytes (64 hex: the full digest; 32 hex: the first 16 bytes). check of a .fr path hashes the file at artifact relative to the module directory. A missing file or a mismatch is unauthenticated; digest-required imports fail with E200. Hex without readable bytes is not a fixture profile. The source-manifest JSON uses the same "digest": "fixture" versus hex distinction.

2.4 Imports #

Modules may import another module by name and version. Digests and aliases match the source-trust story above.

.fr
import MA.TrustLaw.Fixture version "2026-08-23"
import Agency.FOIARegulations version "fixture-2026-08-23" {
    digest fixture
    alias FOIARegs
}

CLI check / run of a path can byte-authenticate hex digests against artifacts under the module directory. "digest": "fixture" (or digest fixture in source) is a trust profile, not byte verification. Mill paste does not load manifests or artifact files.

2.5 Entities, propositions, and offices #

Name the parties and the propositions you will later test. A proposition is not a Boolean.

.fr
entity Payer : NaturalPerson
entity Payee : NaturalPerson

proposition InvoiceIssued(person: NaturalPerson)
proposition Eligible(person: LegalPerson, office: Office)

An office is a position someone can occupy. From examples/trust/bryan-revocable-trust.fr:

.fr
office TrusteeOf(trust: Trust) occupied_by LegalPerson {
    cardinality 0..1
    acquired_by Effective(AcceptOffice)
    suspended_by OperativeIncapacity
    lost_by {Death, EffectiveResignation, EffectiveRemoval}
    competence {AdministerTrust, DecideTrustDistributions}
}

Occupies(Bryan, TrusteeOf(BRT)) is a proposition about that office, not a Bool.

2.6 Record and evidence types #

Name structured payloads the case and Observe paths will carry.

.fr
record_type FOIARequest {
    // fields as in examples/foia/foia-request.fr
}

evidence_type PhysicianCertificate {
    // fields as in examples/trust/bryan-revocable-trust.fr
}

These declarations are part of the closed grammar. Copy field shapes from an existing fixture rather than inventing spellings.

2.7 Observations #

An observation names an evidence-shaped fact the evaluator may Observe.

.fr
observation OfficialFilingObservation(record: OfficialFilingRecord)
observation EndOfTenancy(record: TenancyRecord)

Observe still requires a matching case evidence row with observedAt at or before --known-at. Declaring an observation does not invent the record.

2.8 Queries, goals, and effects #

A query is the thing you run. The body is return / require statements or an explicit goal. Fixtures use Evaluate, UniqueOccupant, RunDecision, and StatusOf.

.fr
query due() -> Money<USD> {
    goal Evaluate { USD(100.00) }
}

query acting_trustee() -> LegalPerson ! {Observe, Determine, Interpret} {
    goal UniqueOccupant { office TrusteeOf(BRT) }
}

query paid_on_time() -> Bool ! {Observe} {
    goal RunDecision { decision TimelyPayment }
}

query entity_status() -> EntityStatus ! {Observe, Determine} {
    goal StatusOf {
        status FormedLLC(HarborRobotics)
        when_present FormedLLC(HarborRobotics)
        when_closed_absent NotFormedLLC(HarborRobotics)
    }
}

Evaluate computes a term. UniqueOccupant asks who occupies an office. RunDecision runs a named decision against the case. StatusOf reports a legal status when present, or the closed-absent form when the domain is closed (harbor-robotics.fr).

EvaluateClause is an additional query plan used by some instruments (for example examples/prenup/ava-noah.fr):

.fr
query provision_result() -> ... ! {Observe, Determine, Interpret} {
    goal EvaluateClause { /* clause plan */ }
}

The effect row ! {Observe, Determine, Interpret} is permission, not a promise that the engine will invent evidence. If the case does not supply what the effect needs, the outcome is suspended. run never fills that request. See Outcomes and Cases and time.

2.9 Automatic versus judgment #

Mark a query automatic only when the answer is mechanical and the effect row is empty.

.fr
query automatic pay_due_immediately(discharged: Bool) -> Bool {
    return discharged
}

query waiting_time_penalty() -> Bool ! {Determine} {
    goal Evaluate {
        require determined WillfulFailureToPay(Employer)
            using Determine
    }
}

An automatic query that reaches Determine, Observe, or Interpret is E420. Willful failure is a judgment, not a Bool you compute in the module. The waiting-time query is allowed to suspend.

A judgment declaration names who decides a proposition, what record it needs, and what happens on established / rejected / otherwise. The trust fixture's incapacity judgment requires two distinct physician certificates and otherwise suspends NeedJudgment. The language will not collapse "the physicians have not spoken" into false.

2.10 Require, return, and sequential evaluation #

Statements in a block run left to right. Several statements lower to a seq; the last value is the result. require is a gate: true continues, false suspends and does not return the later value.

.fr
query q() -> Int { require true; return 7 }
query r() -> Int { require false; return 7 }

q is determinate 7. r is suspended (needCustom / requirement failed). That is why Getting started runs both. Nested seq under +, a call, or if resumes by skipping the completed prefix, so a later term does not re-run an earlier attach.

require determined P using Determine requests a competent determination instead of treating P as a Bool.

2.11 Calc, conditionals, money, and durations #

calc is a total, effect-free function. It must not recurse (E530).

.fr
calc return_deadline() -> Duration<counted_days> {
    return 21 counted_days
}

calc federal_hourly_floor() -> Money<USD> {
    return USD(7.25)
}

query automatic deadline_running(end: Time, as_of: Time) -> Bool {
    return as_of <= end + return_deadline()
}

Money is USD(100.00), never an untyped decimal. Durations carry a calendar kind (counted_days, calendar_days, working_days, days, hours, minutes, seconds). 21 counted_days is not 21 days.

if / else is Boolean control flow. The condition must be a Bool, not a proposition. prelude/tax.fr uses it on amounts:

text
if amount <= 11925.00 {
    amount * 0.10
} else {
    if amount <= 48475.00 {
        11925.00 * 0.10 + (amount - 11925.00) * 0.12
    } else {
        if amount <= 103350.00 {
            11925.00 * 0.10 + (48475.00 - 11925.00) * 0.12 + (amount - 48475.00) * 0.22
        } else {
            17651.00 + (amount - 103350.00) * 0.24
        }
    }
}

This is a rejected guard (E310):

.fr
query bad() -> LegalPerson {
    goal Evaluate { if Incapacitated(Bryan) { Bryan } }
}

Use when operative P on a rule, or require determined P using Determine in a query. Prop has no conversion to Bool.

2.12 Rules #

A rule fires when a guard holds, then derives or establishes a proposition. The current staged worklist is bounded and specialized (implementation-status); this is not a general rule engine, and prescriptive duties / full transaction commit are not that worklist. The kind is derive, constitutive, or prescriptive.

.fr
rule InitialTrustee : constitutive
    from Instrument.clause("1.2")
{
    when operative TrustInstrumentExecuted(BRT) in TrustCreation(BRT)
    then establish Occupies(Bryan, TrusteeOf(BRT))
}

when operative P tests legal status. when determined P tests a competent determination already on the case. then derive and then establish are the usual consequences. Guards must use operative, determined, assumed, or necessarily — not a bare proposition. The successor rule in the trust fixture also select unique candidate from nominations_for(...) with require unique nomination_rank. A tie is not a silent pick.

2.13 Interpretation families #

When the instrument still admits more than one reading, declare the family and what each alternative establishes.

.fr
interpretation_family DeadlineMeaning {
    alternative Strict {
        defines GracePeriod(0) as established
        defines StrictDeadline() as established
        defines ExtendedDeadline() as not_established
    }
    alternative Extended {
        defines GracePeriod(15) as established
        defines StrictDeadline() as not_established
        defines ExtendedDeadline() as established
    }
}

Each defines P as established or defines P as not_established is a claim in that world. The case lists still-admissible alternatives under admissibleCompletions.interpretations. run does not pick Strict because it is written first. If the query needs a reading and the case has not selected one, the outcome is suspended (needInterpretation).

The trust fixture binds a family to a clause and names a selector (explicit_instrument_definition or controlling_interpretation or request Interpret). That is how a court selection on the case becomes operative. It is not a default vote.

2.14 Nominations #

A nomination is a ranked candidate for an office.

.fr
nomination Alice for TrusteeOf(BRT) rank 1
    from Instrument.clause("4.4.a")

nomination Bob for TrusteeOf(BRT) rank 2
    from Instrument.clause("4.4.b")

Rank 1 is higher than rank 2. Duplicate ranks for the same office are E410. Rank is not occupancy: UniqueOccupant still needs an occupancy record, eligibility, and any required acceptance. Open eligibility stays suspended, or becomes contingent under CLI explore with declared bounds. It does not collapse to the first name on the list.

These constructs appear in fixtures (trust, FOIA, prenup, minimum wage). They are status-qualified: parsed and checked, with specialized evaluation paths — not a general operational law engine. See implementation-status.

.fr
power SettlorAmendmentPower { ... }
legal_act AcceptOffice(candidate: LegalPerson, office: Office) { ... }
conflict_doctrine ChildSupportCannotBeAdverselyAffected ...

When staged effects disagree and no unique doctrine applies, the outcome kind is normConflict (or a needConflict request). List order is never a silent tie-break.

2.16 Duties #

A duty names bearer, claimant, attachment, content, and due time. From tests/programs/late-payment.fr:

.fr
duty PayInvoice {
    bearer Payer
    claimant Payee
    attaches when operative InvoiceIssued(Payer)
    content USD(100.00)
    due 0 counted_days after invoice_date
}

query obligation_status() -> String {
    goal Evaluate { duty_status(PayInvoice) }
}

duty_status(Name) looks up that duty declaration plus the case on the implemented specialized duty path (see late-payment fixtures and implementation-status). It does not invent performance and is not a general legal-duty / transaction engine. Status is one of Unresolved, Attached, Performed, Breached, Cured, Discharged. A late perform can remain Performed with breached: true. Changing due 0 counted_days to due 15 counted_days changes when the same case becomes Breached; see late-payment-extended.fr.

Declaring a duty does not attach it. Attachment waits on the when guard. A kind: duty event on the case does not commit performance unless an authority grant covers the action, or the event is an explicit assumption. That gate is in Cases and time.

2.17 Transactions and quantifiers #

transaction { ... } blocks exist in the grammar and are exercised by tests/programs/transaction-atomic.fr. Support is partial — not a full atomic commit engine for arbitrary legal acts.

for_all / exists quantify over finite declared domains (and closures where required). Open domains suspend. Nested / open-world theorem proving is not implemented. Prefer reading implementation-status before treating a quantified verify as a proved theorem.

2.18 Scenarios (in-module) #

A scenario block names overlay hypotheses for fixtures that do not ship companion JSON case files (for example under examples/states/). It is not a silent default for run.

.fr
scenario InsideCityHalfAcre {
    assume OccupiesAsResidence(Owner, Home)
    assume InsideMunicipality(Home)
    assume within_urban_acreage(0.5)
    at 2026-09-17T12:00:00-04:00
}

Grammar: ScenarioDecl in grammar.ebnf. Case JSON can carry analogous overlay rows as assumptions (id, payload); CLI run --scenario applies them, and the mill treats a nonempty assumptions list as scenario mode. Default operative run does not. See Cases and time and CLI.

2.19 Verify #

A verify block is a named property. v0.1 discharges Boolean literals:

.fr
verify Trivial {
    assert true
}

assert true proves. assert false is a counterexample. Other formulas parse, but the bounded verifier does not currently obtain a covering proof of them:

shell
cargo run -p fidryn-cli -- verify PATH --property NAME

reports unknown rather than pretending they are theorems. Fixture modules often write honesty properties in English-shaped assert lines (assert automatic pay_due_immediately has empty effect row). Treat those as documentation the checker records as a verify item, not as a solved proof. The empty-effect-row rule for automatic is E420 whether or not a verify block repeats it.

2.20 What the language will not do #

Fidryn will not hide judgment in a Bool. A proposition is a Prop. if Incapacitated(Bryan) is E310. Write operative, determined, assumed, or necessarily, or request Determine.

Fidryn will not invent a completion. run evaluates the case you supplied. Missing interpretation, evidence, or choice yields suspended. An empty admissible set is inconsistent or suspended, never a vacuous determinate answer. explore searches only the finite domains you declared.

Fidryn will not treat Prop as Bool. defines Eligible(Alice, TrusteeOf(BRT)) as not_established is not false. It is a reading of a proposition in one named alternative.

Those three refusals are the language. The CLI will not choose a completion either. The examples show the refusals in larger fixtures. The Mill will not live-file.

Edit this page on GitHubView as Markdown

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.