UI contract 1
A module defines its GUI as data. The console draws all of it with its own templates, and no module HTML, CSS or JavaScript ever runs in the console origin. Rich UIs that data cannot express use a sandboxed iframe served from a separate origin.
- Models:
oarbank_sdk.ui. - Schemas:
schemas/ui-page-1.schema.json, and the[ui]and[[operations]]parts ofmanifest-1. - Reference modules: examples/toy (a frame using the bridge), examples/reel (media components, datasets, checkpoints, downloads and an upload link), examples/modelserver (services), examples/gpuinfo (nodes’ GPU APIs, the platform matrix) and examples/taskbench (secrets, container images).
- How-to: Build your module’s GUI.
Versioning
Section titled “Versioning”requires.ui_contract = ">=1.0,<2"in the manifest. The installer refuses a module outside the host’s range.- The host announces the contract version it renders in
initialize(host.capabilitiescontainsui_contract:1.<minor>). The current minor is 1.2. Minor 1.1 added the media components; 1.2 adds host queries and fields for what cores 2.2 to 2.5 do for a module, links to downloads, the module’s core tabs and uploads, and the frame context andread.mediaon the bridge. - Within a major, changes are additive only. A component may declare
requires = "1.<minor>"plusfallback(placeholderordrop), so a newer page still renders on an older host.oarbank-sdk checkrefuses a component without it when it uses something newer than 1.0: a newer component or cell type, a newer host query, a field a newer minor added to an older host query (by name: infields, a column, akvitem, or a component’sfield), or a newer link. - An unknown component, or an invalid prop found at render time, renders as a placeholder carrying a developer note. It never breaks the page.
Where modules contribute (placements)
Section titled “Where modules contribute (placements)”| Slot | Renders | Limit | Host rules |
|---|---|---|---|
module.overview |
First tab of /modules/<id> |
1 page | Core tabs always follow it: Health, Settings, Versions, Operations, Audit |
module.page |
Further tabs, at /m/<id>/<page> |
6 pages | Ids match ^[a-z0-9][a-z0-9_.-]{0,63}$ |
job.detail.panel |
Job page, beside the core sections | 2 panels | when filters them, e.g. job.module == self |
node.detail.panel |
Node page | 1 panel | Shown where the module is certified |
campaign.panel |
Campaign page | 1 panel |
The Modules navigation entry, the home page and every core page belong to the core. Modules reach the home page only as inbox alerts, with namespaced reason codes.
ui/pages/<id>.json and ui/panels/<id>.json are static documents covered by the bundle digest:
{"ui_contract": "1.0", "title": "Toy", "vars": [], "body": [ <component>, ... ]}The body holds components, at most 40 per container:
| Group | Components |
|---|---|
| Layout | section (title, span 1, 2 or full), tabs (up to 8), columns (2–3; they stack on phones) |
| Display | text, markdown (paragraphs, emphasis, code, lists, typed internal links), kv, stat, status, progress, callout, empty |
| Data | table (typed columns, paging, sorting, up to 4 row actions), chart (line, bar, scatter, histogram, parallel_coords; a text summary is required), logs, json |
| Input | form (restricted JSON Schema plus hints; submit names an operation), filter_bar (page variables that are pushed to the URL) |
| Action | action (an operation), link (a typed reference: job, node, dataset, campaign, page, an allowlisted https URL, and in 1.2 tab, upload and download; see Links) |
| Media (1.1) | media (one image, video, audio or text artifact), gallery (a grid of images or videos), compare (two images side by side or with a slider) |
| Frame | iframe (a view from [[ui.iframes]]) |
Values are raw and typed. The host formats them:
- Cell types:
text,number,integer,percent,bytes,duration,relative_time,timestamp,bool,digest,code,status,job_ref,node_ref,dataset_ref,campaign_ref,artifact_ref(1.1: an artifact reference, see Media),link. - Formats:
.Nf,.Ne,.N%,d,,d,s,d/d, with an optional leading+. - Columns may declare
direction(minormax). That is what makes “best” and good/bad colouring generic. - A wrongly typed value renders as “—”.
Styling is semantic only: tone ∈ ok, warn, error, info, neutral, running. There is no colour, class or style.
Visibility uses when, a small comparison grammar the host evaluates in Python over a fixed context: row.*, job.*, node.*, campaign.*, user.role (the signed-in viewer’s role: viewer, operator or admin), setting.*. There is no client-side expression language.
Links are typed references the host turns into its own URLs; a reference it cannot resolve renders as text:
| Target | Goes to |
|---|---|
job, node, dataset, campaign |
the console’s page for it; cells of type job_ref, node_ref, dataset_ref, campaign_ref link the same way |
download: true (1.2), beside dataset or campaign |
its download: the dataset’s files, or the campaign’s artifacts, as a zip. A dataset_ref or campaign_ref column with "download": true links each cell to its download |
page |
one of the module’s pages |
tab (1.2) |
the module’s own core tab: secrets (only for a module that declares secrets) or health |
upload (1.2) |
{kind, then?}: the console’s folder upload with this module and kind (one of its [datasets].kinds) filled in. With then = "self.<verb>", an operation whose target = "dataset", the host offers that operation on the new dataset once it is registered, with its own title, tier and confirmation, and then returns to the page |
url |
an https URL in the manifest’s ui.external_urls, in a new tab |
Every data component names a source, which is one of two kinds. The console never waits on the module for either.
- Host query (
{"query": <name>, ...}):<name>comes from a closed catalogue (below).- Every query is filtered to the module’s own rows: datasets are the module’s own and the operator’s (unowned) of the module’s kinds, never another module’s; events are those about the module or one of its jobs or campaigns. No query returns a secret’s value.
- Options:
fields,params(literals, or$route.*,$var.*,$node,$job,$campaign,$self;$job,$nodeand$campaignare the id of the job, node or campaign a panel or frame is shown for),group_bywithagg(count,mean,median,min,max,p95,sum),order_by,limitof at most 200. A query filters on its own params only (ui.QUERY_PARAMS); the others are ignored. The console and the preview shape rows with the same code (oarbank_sdk.render.shape). - Each query runs under a 250 ms budget.
- Module view (
{"view": <id>}):- Declared in
[ui.views.<id>]with ashape(rows,kv,series,stat),columns,paramsandinputs(for exampleresults,datasets:<kind>,store:<collection>).datasets:<kind>is owner-scoped as thedatasetsquery is. - oarbankd calls
ui.view.computewhen the inputs’ data version changes (debounced), or everyrefresh_s(at least 300). - oarbankd validates the result against the declaration (
ui.validate_view: shape, row limit, and for rows only the declared columns) and stores it. The console reads it like any other row. - A module that is down shows its last values with a “computed at” watermark.
- Declared in
| Query | One row per | Fields (1.2 additions in italics) | Params |
|---|---|---|---|
results |
accepted result | result_id, job_id, node_id, value, at, digest, the result’s scalar fields |
job_id, node_id |
jobs |
job | job_id, state, kind, dataset_id, priority, created_at, done_at, exec_failures, stage, campaign_id |
job_id, state, kind, dataset_id, campaign |
attempts |
attempt | attempt_id, job_id, node_id, state, phase, cpu_s, granted_at, ended_at, end_reason, rss_gb, module_version, resumed_from_attempt, resumed_from_node, resume_digest |
attempt_id, job_id, node_id, state |
campaigns |
campaign | campaign_id, name, state, priority, weight, labels, created_at, finished_at, placement_mix, placement_unit, placement_pin, bound_class, binding_state, binding_source, stranded_since |
campaign, state |
datasets |
dataset | dataset_id, kind, created_at, its meta’s scalar keys, owner (module, operator), module, platform, files, size, origins (hosts), pinned |
dataset_id, kind |
module_settings |
(one) | the module’s settings at fleet scope: every declared key, the owner’s value else its default | |
module_events |
event | event_id, ts, kind, reason, node_id, job_id, campaign_id |
kind, job_id, campaign |
nodes |
node | node_id, hostname, lifecycle, desired_state, online, module_state, last_heartbeat_at, platform, os, arch, os_version, gpu_apis_host, gpu_apis_containers, container_gpu, container_runtime (wslc on Windows), container_state (ready, starting, missing, failed, absent), container_platforms, container_detail, container_missing ([{what, detail, fix}]), container_fixes, services (this module’s, as services rows), service_health, folders (this module’s: {id: {access, status}}), folders_ok, enforcement ({capability: state} for what this module’s sandbox needs), sandbox_gaps |
node_id |
node_metrics |
sample | ts and the node’s telemetry |
node_id (required) |
store |
document | the document and _key |
collection (required), campaign |
secrets |
declared secret | name, description, set, fingerprint (keyed, as the Secrets tab shows it), changed_at, changed_by, node_values, stages, coordinator, unreadable |
name |
checkpoints |
open job with a checkpoint | job_id, attempt_id, node_id, generation, seq, files, size, at, digest |
job_id, node_id |
services |
node and service | node_id, hostname, service, health, state (ready, starting, stopped), stopped_reason (held: <reason>, disabled, withdrawn, gpu api missing, idle), error, gpu_api_missing, lifecycle, users, endpoint, reported_at |
node_id, service |
pins |
pinned dataset | dataset_id, kind, platform, files, size, state (registered, missing, conflict), conflict, alert |
dataset_id |
images |
container image first run | digest, image, set_name, key_sha256, first_run_at, node_id, attempt_id, registry, repository, platform |
set_name |
platforms |
platform | platform, runner (supported, unsupported, undeclared), reason, coordinator (supported, unsupported, any), coordinator_reason, nodes, online, certified, doctor_failed |
platform |
A list value in a text cell is shown joined with commas. A field a node does not report is null.
Actions
Section titled “Actions”Buttons, row actions and form submits name an operation. That is either a core operation id, or self.<verb> for one of the module’s own [[operations]], which is registered at install as mod.<module>.<verb>.
- The host draws the friction. The button label is the registry title, and module
hinttext is only a secondary line. The tier comes from the registry. T1 confirms in the browser. T2 and T3 open the host’s plan page, built fromop.plan, and T3 asks for a typed confirmation string the host generates. The audit record comes from the host. - The viewer’s role. A button whose operation needs a higher role than the viewer’s (
min_role) is drawn disabled, naming the role; oarbankd refuses it anyway. - Effective tier is the higher of the declared tier and the floor of its effects:
jobs.cancelT1,campaigns.cancelT2,datasets.deleteT2,store.deleteT1,externalT1. An effective tier of T2 or T3 needspreview = true, and so anop.planimplementation. - Execution.
op.applyreturns effects: core changes the host applies on its single writer, under the same checks as any operation. A module update that adds an operation or effect, or lowers a tier, is shown as a diff at install and needs the owner’s approval. - Responses map to htmx without module markup:
toast,refresh,redirect,joborerrors(keyed by JSON Pointer).
Form schemas are restricted JSON Schema:
type,enum,const, bounds,pattern, andformat∈date-time,duration,uri,hostname;default,description,oneOf, local refs only.
A form never takes a credential: a value handed to an operation reaches module code and the plan. Declare it in
[[secrets]] instead (manifest.md); the owner sets it through the core, and oarbank-sdk check
refuses x-secret in a form schema.
Hints set order, grouping, help and a widget from the host registry. An unknown widget falls back to the default widget for the type.
An object or array property is edited as JSON text (field name pj.<name>); the host parses it and validates the whole parameter set against the schema before forwarding it.
The host validates input before forwarding it. The module returns semantic errors keyed by JSON Pointer.
Modules whose results are media show them without an iframe: generated images and grids, rendered frames, encoded
video, transcripts. Each component sets requires = "1.1" and a fallback (the page check refuses one without), so a
1.0 host draws the fallback.
{"type": "gallery", "requires": "1.1", "fallback": "placeholder", "kind": "image", "source": {"view": "frames"}, "field": "frame", "caption_field": "seed", "columns": 4}{"type": "media", "requires": "1.1", "fallback": "drop", "kind": "video", "source": {"view": "renders"}, "field": "clip"}{"type": "compare", "requires": "1.1", "fallback": "placeholder", "source": {"view": "pair"}, "left": "a", "right": "b", "mode": "slider", "labels": ["seed 1", "seed 2"]}-
mediashows one artifact (kind:image,video,audioortext) from the first row of its source;galleryone image or video per row, each by its thumbnail when it has one and linked to its job;comparetwo images from the first row. -
Artifact references. The named field holds
{"job": <id>, "artifact": <name>, "path": <path>}(a file of a job’s canonical result) or{"digest": <sha256>, "thumbnail"?: <sha256>}(a blob the module can see: its files, its datasets and its jobs’ artifacts, and the operator’s datasets). A view declares such a column with typeartifact_ref(core 2.5), since only declared columns reach the console; a table shows it as its artifact and path. -
Ownership. The host checks every reference on every render: a job of this module with that artifact file, or a digest the module can see. Anything else renders as a placeholder, and no URL is made.
-
Bytes come only from the module origin, never the console’s: the host serves each checked reference at a short-lived capability URL on the origin it serves frames from, which carries no session. It sniffs the file’s first bytes and serves only an allowed type for the component’s kind, with exactly that
Content-Type,X-Content-Type-Options: nosniffandContent-Security-Policy: sandbox:Kind Allowed Size cap imagePNG, JPEG, WebP, AVIF 64 MiB thumbnails PNG, JPEG, WebP, AVIF 1 MiB videoMP4, WebM 16 GiB audioMP3, M4A, Ogg, WAV 1 GiB textUTF-8 text: plain text, VTT, SRT and Markdown, all shown as plain text 4 MiB SVG, HTML and anything else are refused, whatever the file is called. Video and audio honour
Rangerequests.oarbank_sdk.mediais the allowlist (sniff,problem), shared by the console andoarbank-sdk preview. -
Thumbnails come from the module. A runner names a small preview image for any result file (
artifacts[].files[].thumbnail, envelopes.md); the host never transcodes module media. -
Text is shown in a sandboxed frame with no scripts; images, video and audio in the console’s own elements.
The iframe placement
Section titled “The iframe placement”[[ui.iframes]] declares id, entry (an HTML file in the bundle), title and bridge capabilities.
Serving and sandboxing:
- The host serves the frame from the module origin: a separate listener, never the console origin. It carries a CSP whose
sandboxdirective allows scripts and forms and nothing else. - The host embeds it with
sandbox="allow-scripts allow-forms", neverallow-same-origin. The frame therefore has an opaque origin, no cookies, and no access to the console DOM.
The bridge:
-
After load, the host transfers a
MessagePortin a message{type: "oarbank.bridge", module, view, context}. Every call goes through that port as{id, method, params}and is answered with{id, result | error}. -
context(1.2) is the subject the frame is shown for:{job}on a job panel,{node}on a node panel,{campaign}on a campaign panel, plus the page’srouteandvarvalues. The host sends it with every read and interpolates$job,$node,$campaignserver side; it is never an authority (every read stays owner-scoped). -
Methods, each available only if declared in
bridge. The console’s script refuses an undeclared method before it makes any request, and the console’s server checks the frame’s declaration again on every request:Method Answer read.querythe same catalogue, scoping and shaping as pages read.viewthe stored view (a campaign-scoped view reads the context’s campaign) read.media(1.2){src, thumb, job}for an artifact reference of this module: capability URLs on the module origin, checked as the media components’ are. The frame shows them with<img>,<video>or<audio>(its CSP allowsimg-srcandmedia-srcon the module origin; it cannot fetch)request.operation{op, target, params}: what a page action may name,self.<verb>or a core operation. The viewer’s role must meet itsmin_role, and a core job, campaign or dataset operation must name one of the module’s own. The host shows its own confirmation outside the frame, with the registry title, tier and target, for every tier, then posts it as a page button does, with the session’s CSRF token (which the frame never sees) andparamsas JSON; T2 and T3 continue on the plan pageresizebounded by the declared height limits navigate{to}: a typed reference (aslink, never a URL); the host maps it to one of its pages and the top page goes there -
A frame can never apply an operation itself, never read another module’s data, and never reach oarbankd.
Tooling
Section titled “Tooling”oarbank-sdk checkvalidates the manifest, every page file, and the cross-references to views, operations, iframes, form schemas and external URLs.oarbank-sdk previewrenders the pages with the published console renderer, under the same CSP, against fixture data:fixtures/ui/queries/<query>.json, shaped with the console’s code; views computed fromfixtures/ui/inputs.jsonand validated as oarbankd validates them; panels with the subject infixtures/ui/context.json; media references resolved to files infixtures/ui/media/({job, artifact, path}is<artifact>/<path>there), served through the same allowlist. It enforces CSRF and the bridge’s capabilities as the console does.oarbank-sdk preview --checkrenders every page and panel without a server and runs axe-core (WCAG 2.0/2.1 A and AA, best practice) in Node with jsdom; serious or critical violations fail it. It needsOARBANK_SDK_NODE_MODULES(anode_moduleswithaxe-coreandjsdom) and says when it skipped.- The conformance kit’s
uisuite computes every view from the fixtures and validates it, renders every page and panel, and runs the axe check where it can.
Source: spec/ui-contract.md in the oarbank-sdk repository