§ 5 · Run
Fidryn mill
On this page
The mill is a loopback-only web UI for checking, running, exploring, and rendering Fidryn source on this machine. Start it with the CLI:
fidryn ui [--port N] [--no-open]Default port is 8751. The process listens on 127.0.0.1 only. It never
binds 0.0.0.0 or other interfaces. There is no filing route. Live
filing is not available from the mill.
See getting started for a first module, and the
CLI for path-based check / run / explore / render /
file.
5.1 Start #
From a clone:
cargo run -p fidryn-cli -- ui --no-openOr, after cargo install --path crates/fidryn-cli:
fidryn ui --port 8751 --no-openOn success, stderr prints:
fidryn mill on http://127.0.0.1:8751
127.0.0.1 only. live filing is disabled.Without --no-open, a further line says browser auto-open is not linked
and you should open the URL locally. This build does not launch a
browser. Ctrl-C shuts the server down. If the port is taken, the process
exits 1 with
127.0.0.1:PORT is already in use. Stop that process or pass --port.
5.2 Routes #
| Method | Path | Body | Success |
|---|---|---|---|
GET | / | none | web/index.html (text/html; charset=utf-8), with the security headers below |
GET | /assets/fidryn.css | none | site/assets/fidryn.css, the design system the site also uses (text/css; charset=utf-8) |
GET | /assets/mill.css | none | web/mill.css, the mill's own styles (text/css; charset=utf-8) |
GET | /assets/mill.js | none | web/mill.js, the mill app (text/javascript; charset=utf-8) |
GET | /favicon.svg | none | site/favicon.svg (image/svg+xml) |
GET | /fonts/{name} | none | fraunces.woff2, plex-sans.woff2, plex-mono-400.woff2, or plex-mono-500.woff2 from site/fonts/ (font/woff2); any other name is 404 |
GET | /api/health | none | plain text ok |
GET | /api/samples | none | JSON array of the built-in samples, each {id, title, blurb, source, case, query, validAt, knownAt, action, expect} |
POST | /api/check | JSON CheckRequest | JSON {ok, diagnostics} |
POST | /api/run | JSON EvalRequest | { "ok": true, "report": <evaluation-report>, "opinion": [<sentence>, ...] } |
POST | /api/explore | JSON EvalRequest | same transport as /api/run |
POST | /api/render | JSON RenderRequest | JSON {ok, text?, error?} |
The page, its two stylesheets and script, the favicon, the fonts, and
the samples are compiled into the fidryn binary; the mill reads no
files at runtime. The page, stylesheets, script, favicon, and fonts are
sent with Cache-Control: no-cache.
GET / also sends
Content-Security-Policy: default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'none',
X-Content-Type-Options: nosniff, and Referrer-Policy: no-referrer,
so the browser runs no inline script or style on the page and will not
show it inside a frame. In a sample, source is the text of a
repository fixture and case is the text of a case file, or the empty
case record for the first two samples (case is JSON text, not a
parsed object); expect is the outcome kind that action returns
for it.
There is no POST /api/file, /api/filing, /api/submit, or
/api/live. Those paths return 404.
5.3 JSON field names #
Names below are the serde fields the mill actually reads. EvalRequest
uses camelCase. CheckRequest and RenderRequest do not.
5.3.1 POST /api/check #
{"source": "<fidryn module text>"}| Field | Type | Required |
|---|---|---|
source | string | yes |
HTTP status is 200 in both cases. Success is {"ok": true, "diagnostics": []}.
A failed check is {"ok": false, "diagnostics": [...]}. Each diagnostic
object has code, message, primary_span, related_spans, and
suggestion (Rust field names, snake_case).
5.3.2 POST /api/run and POST /api/explore #
{
"source": "<fidryn module text>",
"query": "q",
"case": {},
"bounds": null,
"validAt": "2033-01-01T00:00:00Z",
"knownAt": "2033-01-01T00:00:00Z"
}| Field | Type | Required |
|---|---|---|
source | string | yes |
query | string | yes |
case | JSON value | no (omitted, {}, or null is an empty case) |
bounds | JSON value or omitted | no; used only by /api/explore |
validAt | RFC 3339 string | yes |
knownAt | RFC 3339 string | yes |
case must be a fidryn.case-record/v0.1 object, {}, or JSON null.
bounds follows the same merge rules as CLI --bounds: an
AdmissibleCompletions object (interpretations, evidence, choices)
or a wrapper with admissibleCompletions / admissible_completions.
/api/run ignores bounds. /api/explore still needs a nonempty
completion space on the case, on bounds, or both; otherwise the
outcome is an empty completion set.
A nonempty case.assumptions array puts mill /api/run and
/api/explore into scenario mode (executionMode: scenario on the
report). There is no separate mill --scenario flag; the overlay is
inferred from the case. An empty or omitted assumptions list is
operative. CLI path run still requires explicit --scenario to apply
the same overlay.
validAt and knownAt accept a Z suffix or a numeric offset, the same
as CLI --valid-at and --known-at.
On evaluation success, HTTP 200, and the body is a transport wrapper
{ "ok": true, "report": ..., "opinion": [...] }
(schemas/mill-evaluation-response-v0.1.json). report is the
fidryn.evaluation-report/v0.1 envelope the CLI prints
(schema, executionMode, assumptions, sourceTrust,
verificationMethod, coverage, outcomeDocument). opinion is the
report read as plain sentences, for example
acting_trustee depends on SuccessorEligibility. and
Under I1 it is Alice. for a contingent trust run. Each sentence is a
fixed template filled from report fields, so it never says more than
the report does. ok and opinion are not fields of that report schema
(additionalProperties is false). Nested outcomeDocument is the
fidryn.outcome/v0.1 projection. Pasted compile is
sourceTrust: unauthenticated. run never chooses a completion.
On check failure, HTTP 400:
{"ok": false, "error": "check failed", "diagnostics": [...]}Invalid case, bounds, or timestamps are HTTP 400 with ok false, an
error string (invalid case: ..., the bounds merge message, or
validAt: / knownAt: plus the parse error), and diagnostics: [].
Unknown queries and other engine failures are HTTP 400 (HTTP 500 only
when the engine kind is Internal):
{"kind": "engineError", "error": "UnknownQuery", "message": "...", "ok": false}error here is the engine kind (UnknownQuery, Unsupported,
FuelExhausted, InvalidInput, Internal), not a legal outcome kind.
It is not rewritten as inconsistent.
5.3.3 POST /api/render #
{"source": "<fidryn module text>", "template": "{{module}}@{{version}}"}| Field | Type | Required |
|---|---|---|
source | string | yes |
template | string | yes |
HTTP status is 200 in both cases. Success is {"ok": true, "text": "..."}.
Failure (check diagnostics joined by newlines, or a missing template key)
is {"ok": false, "error": "..."}. Template variables are module,
version, and outside_scope. Missing keys fail closed.
5.4 In-memory compile versus path compile #
Mill source is compiled with compile_source against
SourceManifest::default(). A source_manifest header in the pasted
text is not loaded. No artifact files are read. Hex import digests are
not byte-authenticated. No .fr or manifest is written to disk.
CLI fidryn check PATH (and run / explore / verify / render on a
path) uses Driver::check_path. That authenticates hex import digests
against files in the module directory. The digest "fixture" remains a
test trust profile, not that byte check. Details are in CLI
under source checking and trust.
CLI path compile loads the declared manifest and, for hex digests, hashes
files next to the module. Mill pasted source does neither. A module that
fidryn check accepts can fail in the mill if its imports require a
digest the empty default manifest does not supply. Mill check of a
snippet never proves that on-disk artifacts are intact. Mill must not
gain filesystem access from paste.
5.5 No live filing #
The mill does not call filing adapters. fidryn file on the CLI
is the only submit path, and even there live HTTP needs --live and
FIDRYN_ALLOW_LIVE_FILING=1. A transport receipt is still not Filed.
The HTML page states that live filing is not available from the UI.
5.6 The HTML page #
GET / serves web/index.html, which loads /assets/fidryn.css (the
site's design system), /assets/mill.css, and /assets/mill.js. Those
files, the fonts, and the samples are compiled into the binary, and the
page sends requests only to 127.0.0.1. The response carries a strict
Content-Security-Policy, so the page runs no inline script.
On screens 1200px and wider the page has three columns (samples and history, the editor, and the query with the result); narrower screens stack them in one column. From the top:
- Header. The Fidryn monogram,
mill, the health status (localhost 127.0.0.1 · ok, or a warning when the server cannot be reached), the notice "Live filing is not available from the UI", a link to this guide, and the theme toggle. The theme follows the system until you choose light or dark. - Samples and history. Samples come from
GET /api/samples, each with the outcome kind its default action produces:require-gate,late-payment, and three runs of the trust fixture (open eligibility, court selects I2, one certificate). Choosing a sample fills the module, case, query, and both clocks, then runs its default action; if you have unsaved edits, the rail asks before replacing them. The first visit loadsrequire-gatewithout running it. History lists the last 20 actions of this session. Choosing one reopens its result, and "Restore inputs" puts its inputs back, asking first if you have unsaved edits. - Editor. A segmented control switches between Module, Case JSON,
and Template. The editor has line numbers and syntax highlighting;
Tab and Shift-Tab indent and outdent, and Enter keeps the
indentation; press Escape, then Tab, to move focus out of the editor.
About 700 ms after you stop typing in the module, the page posts it
to
/api/check: each diagnostic gets a wavy underline and a mark in the gutter, and its message appears under the line while the cursor or pointer is on it. Case JSON is checked as you type, with the line and column of the first error. - Query, clocks, and actions. The query field suggests the
module's
querynames.validAtandknownAtmust be RFC 3339.Check,Run,Explore, andRenderpost to the routes above. Ctrl or Cmd with Enter runs; adding Shift explores. - Result. Run and Explore results have three views: Opinion (the
opinionsentences set as a printed page, with the execution mode, source trust, module, andasOf), Table (every field of the outcome and the report envelope), and JSON (the raw report, with Copy). Check showsokor the diagnostics, each with a button that jumps to its line. Render shows the rendered text. Engine errors, invalid input, and an unreachable server are shown in place of a result.
Inputs, the chosen sample, and the chosen result view are kept in the
browser's local storage, so a reload keeps your work. Explore sends
the same body as Run and no separate bounds field; put finite
completions on the case JSON.
5.7 See also #
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.