Fidryn

Docs Mill

§ 5 · Run

Fidryn mill

On this page
  1. 5.1 Start
  2. 5.2 Routes
  3. 5.3 JSON field names
  4. 5.3.1 POST /api/check
  5. 5.3.2 POST /api/run and POST /api/explore
  6. 5.3.3 POST /api/render
  7. 5.4 In-memory compile versus path compile
  8. 5.5 No live filing
  9. 5.6 The HTML page
  10. 5.7 See also

The mill is a loopback-only web UI for checking, running, exploring, and rendering Fidryn source on this machine. Start it with the CLI:

shell
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:

shell
cargo run -p fidryn-cli -- ui --no-open

Or, after cargo install --path crates/fidryn-cli:

shell
fidryn ui --port 8751 --no-open

On success, stderr prints:

shell
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 #

MethodPathBodySuccess
GET/noneweb/index.html (text/html; charset=utf-8), with the security headers below
GET/assets/fidryn.cssnonesite/assets/fidryn.css, the design system the site also uses (text/css; charset=utf-8)
GET/assets/mill.cssnoneweb/mill.css, the mill's own styles (text/css; charset=utf-8)
GET/assets/mill.jsnoneweb/mill.js, the mill app (text/javascript; charset=utf-8)
GET/favicon.svgnonesite/favicon.svg (image/svg+xml)
GET/fonts/{name}nonefraunces.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/healthnoneplain text ok
GET/api/samplesnoneJSON array of the built-in samples, each {id, title, blurb, source, case, query, validAt, knownAt, action, expect}
POST/api/checkJSON CheckRequestJSON {ok, diagnostics}
POST/api/runJSON EvalRequest{ "ok": true, "report": <evaluation-report>, "opinion": [<sentence>, ...] }
POST/api/exploreJSON EvalRequestsame transport as /api/run
POST/api/renderJSON RenderRequestJSON {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 #

json
{"source": "<fidryn module text>"}
FieldTypeRequired
sourcestringyes

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 #

json
{
  "source": "<fidryn module text>",
  "query": "q",
  "case": {},
  "bounds": null,
  "validAt": "2033-01-01T00:00:00Z",
  "knownAt": "2033-01-01T00:00:00Z"
}
FieldTypeRequired
sourcestringyes
querystringyes
caseJSON valueno (omitted, {}, or null is an empty case)
boundsJSON value or omittedno; used only by /api/explore
validAtRFC 3339 stringyes
knownAtRFC 3339 stringyes

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:

json
{"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):

json
{"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 #

json
{"source": "<fidryn module text>", "template": "{{module}}@{{version}}"}
FieldTypeRequired
sourcestringyes
templatestringyes

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:

  1. 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.
  2. 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 loads require-gate without 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.
  3. 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.
  4. Query, clocks, and actions. The query field suggests the module's query names. validAt and knownAt must be RFC 3339. Check, Run, Explore, and Render post to the routes above. Ctrl or Cmd with Enter runs; adding Shift explores.
  5. Result. Run and Explore results have three views: Opinion (the opinion sentences set as a printed page, with the execution mode, source trust, module, and asOf), Table (every field of the outcome and the report envelope), and JSON (the raw report, with Copy). Check shows ok or 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 #

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.