Documentation

# Radiology Transcript Interpreter # Interactive Execution UI Specification **Status:** Normative design draft **Specification version:** 0.1.0 **Target UI version:** 0.1.1 **Supersedes:** *Radiology Transcript Interpreter — Debug UI Design Specification* **Basis:** The conceptual interpretation specification, linguistic-semantic refinement specification, `interpreter.ir.v1`, and the completed first proof of concept **Primary interaction:** Draft transcription → Run → Step through interpretation depth → Inspect a focused object **Visual direction:** Clear, restrained application interface with contextual detail and progressive disclosure ## Contents 1. Vision 2. Technical Introduction 3. Survey of Decisions and Interaction Rules 4. Reference Appendices --- # 1. Vision ## 1.1 Purpose The interface exists to let a researcher provide a transcription, run the radiology transcript interpreter, move forward and backward through the resulting representations, and inspect any semantic object in context. Its central interaction is: ```text write or load transcription │ ▼ Run │ ▼ R0 Source ⇄ R1 Linguistic ⇄ R2 Constructs ⇄ R3 Frames ⇄ R4 Grounding ⇄ R5 Validated │ ▼ select an object and inspect its local explanation ``` The interface is not primarily a long report about an execution. It is an interactive environment for examining one interpretation at different degrees of enrichment. ## 1.2 Governing Principle > **Hold the execution and subject stable while changing how deeply the > interpretation is viewed.** The user should be able to begin with the exact source, move toward the validated result one enrichment step at a time, and then move backward without losing the object or question under investigation. ## 1.3 Design Correction The earlier UI draft made the source transcript the permanent visual anchor and organized the execution as a vertically ordered narrative with a Tufte-inspired evidence margin. That draft established valuable semantic and evidentiary principles, but its page geometry is no longer normative. The new design distinguishes: ```text epistemic anchor interaction anchor ──────────────────────────────────── ──────────────────────────────────── exact source characters interpretation depth plus subject under inspection ``` The source remains authoritative. It does not have to remain the largest or most persistent visual region at every depth. Tufte remains an influence on restraint, typography, comparison, and the adjacency of claims and evidence. Tufte-derived preferences do not determine the application structure, prohibit useful controls or panels, or require a document-and-margin layout. ## 1.4 Desired Experience The interface should feel clean, direct, and conceptually stable. The user should be able to: 1. enter text or load a reviewed test transcription into the same textarea; 2. run the complete interpreter against the exact submitted text; 3. begin at the source representation; 4. move toward more enriched IR or back toward less enriched IR; 5. select a span, mention, construct, referent, frame, grounding, diagnostic, or validation result; 6. retain that subject while moving across interpretation depth; 7. expose related evidence, relationships, provenance, candidates, and raw artifacts as needed; and 8. edit the transcription and deliberately create a new execution. The normal workflow should not require reconstructing the interpretation from JSON, logs, endpoint responses, Prolog terms, or implementation topology. ## 1.5 Scope This specification governs: - transcription drafting and test-data loading; - starting an interpretation; - execution status and completion; - R0–R5 navigation; - object focus and cross-depth explanation; - contextual peripheral information; - semantic HTML, addressability, accessibility, and progressive enhancement; - access to raw evidence; and - the relationship between the interpreter UI and the existing toolchain UI. It does not define: - new interpretation semantics; - new R0–R5 boundaries; - clinical workflow or clinical correctness; - production authentication or authorization; - collaborative editing; - arbitrary code, rule, query, command, or service execution; - the durable-execution storage design owned by the interpreter implementation plan; or - a general ontology browser. --- # 2. Technical Introduction ## 2.1 Existing System Boundary The current research system already contains: - a Go hub and server-rendered Toolchain Debug UI on loopback port `8170`; - a Python linguistic service that preserves exact source characters and emits linguistic and construction evidence; - an SWI-Prolog semantic service that creates mentions, referents, frames, grounding, diagnostics, provenance, and validation; - an `interpreter.ir.v1` contract; and - a deterministic first proof-of-concept result artifact. The existing Toolchain Debug UI answers whether the research machinery is available and verified. The UI specified here answers what one transcription means according to one interpreter execution. These remain distinct applications even when the Go hub serves and links both. The Go hub remains bound to `127.0.0.1:8170`. Tailscale Serve may expose that loopback service to the tailnet. The interpreter services do not bind directly to a Tailscale address. ## 2.2 Empirical IR Shape The current complete POC result contains the following primary collections: ```text source source_spans linguistic_observations mentions constructs referents frames groundings ambiguities diagnostics provenance_edges validation output resource_identities ``` The first retained execution currently demonstrates 145 source spans, 130 linguistic observations, six mentions, three constructs, three referents, three frames, six grounding records, one diagnostic, 25 provenance edges, and eight validation checks. These counts describe the current fixture. They are not UI limits and should not become layout assumptions. ## 2.3 Core UI Concepts The interface introduces a small application vocabulary over the interpreter model. ### Draft A mutable candidate transcription and its drafting provenance. A Draft is not an Interpretation Execution. ### Test Example A reviewed source record that may populate a Draft. Test-example metadata may identify the source of the draft, but it is not semantic evidence. ### Interpretation Execution An immutable attempt to interpret one exact source snapshot under recorded profiles, rules, and resources. ### Interpretation Depth One of the named conceptual levels R0 through R5. ### Interpretation Projection The view of an execution at one interpretation depth. This is sometimes called the “IR at R3” in ordinary conversation, although R0 begins with source rather than a derived IR object. ### Subject Under Inspection The stable object or source region currently being examined. ### Peripheral Detail Information that explains or contextualizes the current subject without replacing the interpretation projection: evidence, relationships, provenance, candidates, diagnostics, identities, and raw representations. ## 2.4 Interpretation Depth The UI uses the conceptual sequence already established by the interpreter: | Depth | Name | Newly emphasized material | | --- | --- | --- | | R0 | Source | Exact submitted transcription | | R1 | Linguistic | Sentences, tokens, UD observations, and imported linguistic evidence | | R2 | Constructs | Mentions, constructs, construction elements, and licensed source roles | | R3 | Discourse and Frames | Referents, frame instances, role bindings, and composition | | R4 | Grounding | RadLex candidates, accepted groundings, ambiguity, and domain context | | R5 | Validated | Validation outcomes and accepted validated-frame output | The levels are conceptual projections, not claims that the runtime executes as six isolated sequential programs. ## 2.5 UI State For a completed execution, the essential UI state is: ```text UIState = (execution, depth, subject) ``` where: ```text execution ∈ InterpretationExecution depth ∈ {R0, R1, R2, R3, R4, R5} subject ∈ ExecutionObject ∪ SourceRegion ∪ {none} ``` Changing depth does not implicitly change execution or subject. Before execution, the essential state is: ```text DraftState = (text, origin, dirty) ``` Draft state and completed-execution state must not be conflated. ## 2.6 Execution Lifecycle The visible lifecycle is: ```text Draft ──Run──► Submitted ──► Running ──► Completed │ └────────► Failed ``` A Completed execution owns immutable source, intermediate representations, final IR, validation, and resource identities. A Failed run may expose a stable failure record and structured diagnostics. It must not masquerade as a completed interpretation or publish R5 output. ## 2.7 Application Architecture The intended responsibility boundary is: ```text Browser │ │ draft form, run request, navigation, object links ▼ Go hub │ │ complete interpretation operation and immutable execution record ├──────────────► Python linguistic service └──────────────► SWI-Prolog semantic service │ ▼ Interpretation execution │ ├── R0–R5 projections ├── object and relationship routes └── raw immutable artifacts ``` The browser does not orchestrate the Python and Prolog services directly. The hub owns the complete run and publishes the execution that the UI inspects. ## 2.8 Terminology “More enriched” means moving toward a greater interpretation depth. “Less enriched” means moving toward source evidence. “Step” means changing the inspected projection of an existing execution. It does not mean invoking one backend stage unless a future specification explicitly introduces live staged execution. --- # 3. Survey of Decisions and Interaction Rules ## 3.1 The Execution Workspace Is the Primary Interface ### Existing meaning The earlier design treated one Interpretation Execution as the primary object but rendered it principally as a long explanatory document. ### Design decision The primary execution view is an interactive workspace. Its stable center is the current Interpretation Projection. Its stable contextual object is the Subject Under Inspection. The Draft preserves a simple conceptual reading order: ```text submitted input → complete R0–R5 stage map → selected-stage output ``` Before Run, the same location displays a preview of the complete stage map and an explicit empty-output state. After Run, the editable input disappears and the execution uses this reading order: ```text complete R0–R5 stage map → selected-stage visual representation └→ peripheral object detail ``` The exact submitted text remains the R0 representation and is linked from the execution header at every depth. It is not repeated in a read-only textarea. The long-form narrative remains useful as a printable or overview representation, but it is secondary to the workspace. ### Entails - R0–R5 navigation is visible without scrolling through every level. - The current depth is always apparent. - Object selection reorganizes contextual detail around that object. - The user may inspect an execution without reading every preceding section. ### Does not entail - The interface is a free-form graph canvas. - Every IR object is displayed simultaneously. - Implementation subsystems become primary navigation categories. ## 3.2 One Textarea Owns Draft Input ### Design decision The New Interpretation view contains one primary textarea for transcription text. The user may type, paste, edit, or populate that textarea from a reviewed Test Example. Test data enters through the same Draft model as manually entered text: ```text Manual entry ───────┐ ├──► Draft.text ──► Run Load test example ──┘ ``` Loading a test example does not run the interpreter. It replaces the mutable Draft text and records the example identity as drafting provenance. ### Required controls The initial form provides: - the transcription textarea; - a small named test-example selector or “Load test data” control; - the active linguistic and semantic profile identities, normally using safe defaults rather than editable arbitrary strings; - a Run action; and - concise input validation or run failure feedback. ### Invariants - `Draft.text` is the only semantic language input. - Test-example annotations, expected constructs, source-row lineage, or hidden report material are never submitted as semantic evidence. - The server interprets the exact received text without trimming, correcting, normalizing, or replacing it. - The source snapshot displayed after completion is the server-recorded input, not an assumed copy of browser state. ## 3.3 Run Creates an Immutable Source Snapshot ### Design decision Run submits the Draft to the complete interpretation operation. A successful run creates a new immutable Interpretation Execution. Formally: ```text run(Draft, Profiles, Resources) = Execution Execution.source.text = submitted(Draft.text) ``` The UI initially opens a newly completed execution at R1, the first visibly enriched representation. R0 remains directly selectable as the exact immutable source anchor. ### Entails - The textarea is an editor before Run, not a live editor of completed source. - A completed Execution contains no textarea; its central object is the selected enrichment representation. - Profiles, rules, models, and ontology identities belong to the execution. - Refreshing or revisiting the execution does not recompute it silently. - A shareable execution URL refers to one stable result. ### Does not entail - Every keystroke invokes analysis. - Editing a prior Draft mutates a completed execution. - A failed run creates valid R5 output. ## 3.4 Step Through Enrichment, Not Runtime Calls ### Design decision Run computes the complete interpretation. Previous, Next, and direct depth selection change only the inspected projection. ```text Run : Draft → Execution Next : (E, Rᵢ, S) → (E, Rᵢ₊₁, S) Previous : (E, Rᵢ, S) → (E, Rᵢ₋₁, S) ``` The initial interface must not require the user to invoke linguistic, construction, semantic, grounding, and validation operations separately. ### Rationale This interaction presents the conceptual enrichment process without falsely claiming that the runtime is manually stepped or that each representation is computed only when its button is pressed. ## 3.5 Projections Are Cumulatively Intelligible ### Design decision Moving toward R5 adds semantic interpretation without making earlier evidence unavailable. Moving toward R0 removes higher-order overlays and returns toward the exact source. At the UI level: ```text Visible(E,R0) ⊆ Visible(E,R1) ⊆ ... ⊆ Visible(E,R5) ``` This relation describes conceptual availability in the workspace. It does not require backend JSON objects to be physically nested or monotonically serialized. Each depth should visually emphasize what is introduced there while retaining local routes to the earlier objects that support it. ### Does not entail - R5 visually overlays all 145 spans and 130 observations at once. - Later representations may silently rewrite or erase earlier evidence. - An object rejected or unresolved at a later depth should be presented as accepted merely because it appeared earlier. ## 3.6 Subject Focus Persists Across Depth ### Design decision Object selection establishes a Subject Under Inspection. Depth navigation preserves that subject. Every object has an introduction depth: ```text birth(o) = least Rᵢ at which o is represented ``` If the current depth is at or beyond `birth(o)`, the projection displays and highlights the object directly. If the user moves to a depth earlier than `birth(o)`, the subject remains pinned and the projection shows its provenance antecedents at that depth: ```text evidenceAt(o, Rᵢ) = objects at Rᵢ reachable backward through provenance from o ``` For example, a selected Location frame remains the subject when the user moves from R5 to R2. At R2, the central view highlights its evoking located-finding construct and role-filling mentions. At R0, it highlights the exact source spans supporting those objects. If no provenance path exists, the interface states that the subject has no representation at the selected depth. It does not select a nearby object by position or guess a relationship. ## 3.7 Central Projection and Contextual Periphery ### Design decision The normal wide-screen geometry is: ```text ┌──────────────────────────────────────────────────────────────────────┐ │ Execution identity R0 R1 R2 R3 R4 R5 Less More │ ├───────────────────────────────────────────────┬──────────────────────┤ │ │ Subject │ │ Current interpretation projection │ │ │ │ relationships │ │ source / annotation / semantic objects │ evidence │ │ appropriate to the selected depth │ provenance │ │ │ candidates │ │ │ diagnostics │ │ │ raw details │ └───────────────────────────────────────────────┴──────────────────────┘ ``` The periphery is contextual, not a permanent table of every fact. It changes with the selected subject and current depth. The initial inspector should organize detail into a small number of semantic groups such as: - identity and status; - roles and relationships; - source evidence; - derivation and provenance; - candidates, diagnostics, and validation; and - raw representations. The exact disclosure mechanism may use sections, tabs, drawers, or another accessible control. No particular widget is mandated by this specification. ## 3.8 Source Authority Does Not Require Permanent Source Geometry ### Design decision The exact transcription remains the canonical evidentiary source. The source may occupy the central projection at R0, appear as annotated text at R1 and R2, and appear as focused excerpts or evidence links at later depths. Selecting any source-backed object must provide a route to its exact full source context and offsets. ### Invariant ```text stored span text = execution source[start:end] ``` ### Does not entail - The complete transcript remains fixed beside every later view. - Normalized quantities or labels replace source wording. - Source adjacency is evidence of semantic composition. ## 3.9 Depth-Specific Presentation ### R0 — Source The central view presents the exact immutable source as a readable source document with minimal execution metadata. Exact source spans remain selectable. When a later subject is pinned, supporting source ranges are highlighted and distinguishable when they overlap. ### R1 — Linguistic The source becomes an interlinear token stream grouped by sentence. Each token presents its surface form with a compact lemma, part-of-speech, and dependency line. Selecting a token reveals its broader object detail, local linguistic neighborhood, evidence, and imported authority. ### R2 — Constructs The view first exposes recognized source phrases as labelled Mention chips, then presents each Construct as a role-oriented card connecting named construction elements to their exact fillers. It must distinguish construct type, construct instance, role, and source material. ### R3 — Discourse and Frames The view presents discourse Referents as entity chips and Frame instances as role-oriented semantic cards. Referenced role values link back to the same Referent identity. Shared identity—such as Measurement.entity and Location.figure referring to the same finding—must therefore be immediately visible. ### R4 — Grounding The view presents explicit subject-to-concept mapping rows. Each row identifies whether its subject is a Mention or Referent and whether the mapping is a candidate or accepted Grounding. Mention, Referent, and Ontology Concept remain distinct objects. Multiple undominated candidates are comparable without repeated navigation. ### R5 — Validated The view assembles accepted frames into readable structured Finding cards with entity, measurement, location, ontology grounding, and unresolved fields. It also exposes the individual validation rules that licensed the output. Ambiguity and diagnostics may remain visible in a valid result. ## 3.10 Peripheral Detail Is Progressive Disclosure ### Design decision The interface initially displays the semantic facts required to identify the subject and understand its immediate role. Deeper evidence is disclosed in place. Examples include: ```text Frame roles evoking construct source evidence why this exists raw JSON Prolog derivation ``` Raw evidence remains locally reachable from the object it explains. A global raw-artifact index may exist, but it is not the ordinary inspection path. Progressive disclosure must not hide status, ambiguity, unresolved roles, or failed validation merely to simplify the page. ## 3.11 Visual Direction and the Tufte Override ### Design decision The visual language remains restrained, but the interface is permitted to use application controls and bounded regions when they clarify state and interaction. ### Basic Web Theme baseline and restrained customization The initial implementation begins with Basic Web Theme as its visual and technical starting point: ```text https://raw.githubusercontent.com/mdashx/basicwebtheme/ 46fe7fcbff91d766a9aca040adf4aec3de26659c/static/assets/css/style.css ``` The source and license remain recorded, but the upstream file is not a pixel-perfect or source-text conformance target. CSS may be added, removed, reorganized, or rewritten when doing so improves the specified interaction. The intended “ten percent” limit is a design guardrail, not arithmetic over bytes, lines, declarations, selectors, or syntax-tree nodes. Approximately ninety percent of the visual language should still feel like Basic Web Theme: semantic HTML, system typography, ordinary controls, readable prose and data, minimal chrome, automatic dark mode, and no dependency on JavaScript for basic presentation. The remaining custom layer may establish the application workspace, stage navigation, focus, comparison, and semantic status needed by this interface. The implementation should retain one compact local author stylesheet and must not introduce a CSS framework, generic component system, utility-class layer, third-party visual dependency, or inline-style sprawl. Compliance is evaluated through design review and the resulting interface, not a mechanical CSS-diff score. The design should prefer: - strong typographic hierarchy; - generous but not wasteful spacing; - a small neutral palette with semantic status accents; - minimal borders and backgrounds; - legible identifiers and source text; - stable placement of depth controls; - comparison by adjacency; and - motion only when it preserves orientation. Cards, panels, tabs, sticky controls, and drawers are not prohibited. They must correspond to real concepts or interaction state rather than supply generic application decoration. The following earlier inferences are explicitly rejected: - that a narrative-plus-margin page is the preferred desktop geometry; - that a long document is inherently more intelligible than an interactive workspace; - that avoiding common UI controls is itself a mark of conceptual purity; and - that source authority requires source dominance at every depth. ## 3.12 Ambiguity, Diagnostics, and Validation Ambiguity is a supported semantic outcome, not a generic error state. Diagnostics belong both to their affected subject and to an execution-level summary. They must not be exiled to logs. Validation is a collection of named semantic checks. A green execution-level status may summarize them, but the user must be able to inspect each check and its subjects. The UI must preserve: ```text valid ≠ completely resolved candidate ≠ accepted unresolved ≠ failed execution diagnostic ≠ crash ``` ## 3.13 Editing and Re-running ### Design decision A completed execution is immutable. “Edit and run again” copies its source into a new Draft. ```text Execution E₁.source │ copy ▼ Draft D₂ ──Run──► Execution E₂ ``` Changing the Draft does not change E₁. Changed rules, resources, profiles, or source create a new execution identity or an explicit duplicate/stale outcome according to the durable execution contract. The UI must never make an old R5 result appear to belong to newly edited text. ## 3.14 Running and Failure States While a run is active, the interface should show: - the immutable submitted source identity; - the operation status; - the profiles and execution identity when assigned; - elapsed time or last update when available; and - structured diagnostics when a stage fails. Refresh must reveal the true current state. Client polling or server-sent events may improve responsiveness but must not own hidden execution truth. On failure, the UI offers a route back to an editable copy of the submitted text. It does not fabricate partial R5 output. ## 3.15 Addressability The initial route vocabulary should support: ```text /interpretations/new /interpretations/{execution} /interpretations/{execution}?depth=R3 /interpretations/{execution}?depth=R3&focus={object} /interpretations/{execution}/artifacts/{artifact} ``` Equivalent path-based object routes may also exist, but depth and focus must be representable in a shareable URL. Following a shared URL should restore the same execution, depth, and subject or return an explicit not-found/stale response. ## 3.16 Semantic DOM The rendered HTML must expose the domain state that the visual interface already knows. At minimum, the document identifies: - execution identity and execution status; - current interpretation depth; - subject identity and type; - every rendered object's stable identity, type, and status; - source offsets for rendered source spans; - important relationships such as evidence, reference, evocation, role filling, grounding, and validation; and - the available depth and object navigation actions. These relationships must not exist exclusively in opaque client state or CSS class names. ## 3.17 Visible Version Identity Every primary Draft and Execution view visibly identifies the application as `UI v0.1.1` in a stable header location. The same value is exposed on the application shell as `data-application-version`. An Execution view additionally displays and exposes these distinct identities: - interpretation contract version, such as `interpreter.v1`; and - IR schema version, such as `interpreter.ir.v1`. Profile, model, ontology, resource, artifact, and build identities remain separately labelled. None of them substitutes for the UI version. The application version has one source in the implementation and is copied neither into templates nor client code as an independent value. Before 1.0, a change to specified user-visible interaction or interpretation presentation increments the minor version; a compatible correction increments the patch version. A build or commit identity may be shown in addition when it is trustworthy, but an uncommitted or unknown build must not fabricate one. ## 3.18 Vanilla-JS SPA and Accessibility The browser experience is a single-page application implemented with a small, dependency-free vanilla-JavaScript module. It intercepts Draft loading, Run, depth selection, object focus, and Previous/Next navigation; replaces the application workspace in place; updates the document title and address bar; and restores addressable state through browser Back and Forward navigation. The SPA uses the server-rendered document routes as its state and rendering contract. It must not maintain a competing browser-only interpretation model, invent client-only execution identities, or make a refresh less truthful. The vanilla-JS layer provides in-place depth transitions, inspector updates, Run feedback, history integration, focus management, and live navigation status. The interactive workflow requires JavaScript. Server-rendered GET routes bootstrap the application and restore deep-linked or refreshed state; they are not a parallel non-JavaScript interaction implementation. Run is a JSON application operation. The SPA sends only the exact transcription and the two allowlisted profile identities to `POST /api/v1/interpretations`. That endpoint returns a JSON execution location or a structured JSON error. It does not return an HTML document. Server-rendered HTML remains the document and projection representation used by stable GET routes. Required keyboard behavior includes: - normal sequential focus order; - operable Run and test-data controls; - operable Previous and Next controls; - operable direct depth selection; - visible focus indication; and - no requirement for pointer-only graph interaction. Previous/Next keyboard shortcuts may be added, but they must not interfere with typing in the Draft textarea. Color, position, and animation must not be the sole carriers of object type, status, selection, or validation state. ## 3.19 Narrow Displays On narrow displays, the current projection remains primary. Contextual peripheral detail moves after the projection or into an accessible bottom drawer associated with the subject. The depth navigator may become horizontally scrollable or use compact Previous/Next controls, but the current named depth remains visible. Peripheral detail must not collapse into an unrelated generic menu. ## 3.20 Security and Source Handling The current reviewed test corpus contains no PII, but future real human transcription may contain sensitive clinical language. The UI therefore must: - avoid third-party scripts, fonts, analytics, or content services; - escape all submitted and interpreted text in HTML; - require JSON content and `X-Rad-NLP-Navigation: spa` on the SPA Run endpoint; a cross-origin script cannot send that custom header without a CORS preflight, and the application grants no cross-origin access; - expose only allowlisted interpretation actions; - avoid embedding source text in logs unnecessarily; and - treat tailnet exposure as research-machine access, not as a production security boundary or clinical deployment claim. ## 3.21 Relationship to the Toolchain UI The Toolchain UI and Interpreter UI may link to one another through resource and execution identities. Every Draft and Execution header includes a prominent Documentation action. The Documentation view begins with the original RadLex-to-Prolog compiler specification, then renders the checked-in interpreter conceptual specification, linguistic-semantic refinement specification, implementation plan, Interpreter UI specification, Toolchain UI specification, and operator manual as authoritative source-backed sections. It also provides a prominent route to the Toolchain UI for system health, monitoring, verification evidence, and further operational documentation. They must retain separate primary concepts: ```text Toolchain UI Interpreter UI ────────────────────────────── ────────────────────────────── Evaluation Interpretation Execution Service / Component Source / Mention / Construct Capability / Seam Referent / Frame / Grounding Verification Validation / Output ``` An interpreter execution may link to the toolchain evaluation or component identities that support it. Infrastructure tables and service controls do not belong in the normal interpretation workspace. ## 3.22 Cross-Cutting Invariants 1. The exact submitted transcription remains recoverable at every depth. 2. A Test Example populates a Draft but contributes no hidden semantic evidence. 3. Run creates a new immutable execution; stepping does not recompute it. 4. Depth navigation preserves the Subject Under Inspection. 5. Earlier-depth evidence remains reachable from every derived object. 6. Mention, Referent, and Ontology Concept remain distinct. 7. Candidate, accepted, rejected, and unresolved states remain distinct. 8. An ontology class never appears visually as a transcript individual. 9. Source proximity is never presented as semantic justification without a licensed relationship. 10. A valid interpretation may contain ambiguity and diagnostics. 11. R5 contains validated structured output and does not require canonical predicate projection. 12. Raw evidence is available but does not define the primary information architecture. 13. The DOM identifies the concepts and relationships rendered to the user. 14. Stable server-rendered GET routes restore the SPA at an addressed execution, depth, and subject after refresh or direct navigation. ## 3.23 Acceptance Criteria The initial UI satisfies this specification when executable tests demonstrate the following behavior. ### Draft and Run - A user can enter arbitrary nonempty transcription text in the textarea. - A user can load the reviewed POC record into that same textarea and edit it. - Loading test data does not automatically run the interpreter. - Run submits only the exact text and allowlisted profile choices as semantic input. - A successful Run creates an addressable immutable execution and opens R1. - Editing and running again creates or resolves to a distinct execution without changing the prior result. - A completed execution contains no textarea; the selected enrichment layer replaces the Draft editor. ### Interpretation Depth - Previous, Next, and direct depth controls cover R0 through R5. - The current depth is visible and addressable. - R0 reproduces the exact submitted source. - R1 exposes linguistic observations. - R2 exposes mentions, constructs, elements, and exact fillers. - R3 exposes referents, frames, roles, and shared identity. - R4 exposes candidate and accepted RadLex grounding distinctly. - R5 exposes individual validation results and accepted validated frames. - R0 through R5 each expose one depth-specific visual representation rather than using an object table or raw JSON as the primary output. ### Subject Inspection - Selecting a frame establishes a stable Subject Under Inspection. - Moving from that frame toward R2 and R0 highlights its provenance antecedents without changing the subject. - Moving forward restores the frame when its introduction depth is reached. - Missing ancestry is stated explicitly rather than guessed. - Peripheral detail identifies relationships, evidence, provenance, diagnostics, validation, resource identities, and raw evidence as available. ### Semantic Integrity - Mention and Referent are visually and structurally distinguishable. - Referent and Ontology Concept are visually and structurally distinguishable. - Unresolved roles remain present. - Ambiguity is not styled as a crash. - Partial interpretation can coexist with a valid result. - Every accepted frame and grounding exposes a path to exact source evidence. ### Web Interface - Execution, depth, focus, object identities, and important relationships are machine-discoverable in the DOM. - Every primary view visibly exposes UI version `0.1.1` and carries the same value as `data-application-version` on its semantic application shell. - Execution views visibly and structurally distinguish the interpretation contract version from the IR schema version. - Run, depth, focus, and Previous/Next transitions occur in place through the dependency-free vanilla-JS SPA layer. - The SPA updates stable URLs and correctly restores them through browser Back and Forward navigation. - JavaScript is served as a local external asset allowed by the page CSP; the interface contains no inline executable script or event-handler attributes. - All controls have accessible names and keyboard behavior. - Stable URLs restore execution, depth, and subject. - Draft and Execution views expose a prominent stable Documentation route. - Documentation exposes the conceptual and refinement specifications and a direct Toolchain health and monitoring route. - Raw artifacts retain their immutable identities and digest checks. - The application remains available through the existing loopback hub and its configured Tailscale Serve proxy without exposing internal services directly. ## 3.24 Deliberately Experimental Presentation Questions The following choices should continue to be refined with additional IR examples rather than prematurely frozen: - whether R1 should add a focused dependency-neighborhood view alongside the sentence-grouped interlinear token stream; - whether R3 should add a compact relation diagram alongside its role-oriented semantic cards; - the best compact representation for overlapping source spans; - whether the contextual inspector uses vertically stacked sections or a small tab set on wide displays; and - how much of a very long transcription remains in the central viewport while a later semantic subject is selected. These experiments may change presentation geometry. They may not change the Draft/Execution boundary, interpretation-depth model, stable subject focus, or source/provenance invariants without revising this specification. --- # 4. Reference Appendices ## Appendix A — Initial Workflow ```text NEW INTERPRETATION Test data: [POC measured and located nodule ▾] [Load] ┌──────────────────────────────────────────────────────────────┐ │ There is an 8mm nodule in the left lower lobe ... │ │ │ │ │ └──────────────────────────────────────────────────────────────┘ Profiles: linguistic.poc.v1 · semantic.poc.v1 [Run interpretation] Interpretation stages [R0 Source] [R1 Linguistic] [R2 Constructs] [R3 Frames] [R4 Grounding] [R5 Validated] Current selected stage output No execution yet. Run the Draft to begin at R1. ``` After completion: ```text INTERPRETATION exec-poc-4cd7522b679092d7 Submitted transcription ┌──────────────────────────────────────────────────────────────┐ │ There is an 8mm nodule in the left lower lobe ... │ └──────────────────────────────────────────────────────────────┘ [R0 Source] [R1 Linguistic] [R2 Constructs] [R3 Frames] [R4 Grounding] [R5 Validated] [← Less enriched] [More enriched →] Current selected stage output: R1 Linguistic Current projection Subject ──────────────────────────────────────────── ─────────────────────── There is an 8mm nodule in the no object selected left lower lobe ... ``` ## Appendix B — Example Cross-Depth Focus Suppose `f-cxn-location-s6-6` is the selected Location frame. | Depth | Central emphasis while the frame remains the subject | | --- | --- | | R5 | The accepted Location frame and its passed validation | | R4 | The grounded finding and anatomy referents participating in the frame | | R3 | Location roles and the shared finding referent | | R2 | The located-finding construct and its figure, relation, and ground mentions | | R1 | Tokens and dependencies supporting `nodule in … lobe` | | R0 | Exact `nodule`, `in`, and `left lower lobe` source spans | The inspector continues to identify the selected frame at all six depths. It also identifies the current antecedents being displayed. ## Appendix C — Semantic DOM Sketch ```html <article id="interpretation-exec-poc-4cd7522b679092d7" data-concept="interpretation-execution" data-execution-id="exec-poc-4cd7522b679092d7" data-execution-status="completed" data-depth="R3" data-subject-id="f-cxn-location-s6-6"> <nav aria-label="Interpretation depth" data-concept="depth-navigator"> <a href="?depth=R2&amp;focus=f-cxn-location-s6-6">R2 Constructs</a> <a aria-current="step" href="?depth=R3&amp;focus=f-cxn-location-s6-6"> R3 Frames </a> <a href="?depth=R4&amp;focus=f-cxn-location-s6-6">R4 Grounding</a> </nav> <main data-concept="interpretation-projection" data-depth="R3"> <section id="f-cxn-location-s6-6" data-concept="frame" data-frame-type="Location" data-status="accepted"> ... </section> </main> <aside aria-label="Subject under inspection" data-concept="subject-inspector" data-subject-id="f-cxn-location-s6-6"> ... </aside> </article> ``` This markup is illustrative. The required semantics are the stable execution, depth, subject, object types, statuses, source locations, and relationships. ## Appendix D — Design Provenance ### Interpretation depth as the interaction anchor **Original input** > “Hit a button and flip through the enriched or less enriched IR from my > source to end.” **Context summary** The earlier draft used a Tufte-inspired long narrative with source as the dominant visual anchor. **Design contribution** **Human-led correction.** The author replaced static page geometry with a depth-oriented interaction model. The source remains authoritative, while R0–R5 navigation becomes the principal way of understanding the execution. **Resulting specification rule** ```text UIState = (execution, depth, subject) ``` Depth may change without changing execution or subject. ### Draft, Run, and inspect **Original input** > “Provide in a text area or have the area populated with test data, and then > run and step through the IR.” **Context summary** The design had described completed execution inspection but had not made the creation workflow its central interaction. **Design contribution** **Human-led direction.** The author established the complete interaction spine: one editable Draft, optional reviewed test-data population, one atomic Run, and stepwise inspection of the completed representations. **Resulting specification rule** ```text Draft ──Run──► immutable Execution ──inspect──► R0 ⇄ ... ⇄ R5 ``` Run computes the execution. Stepping changes its inspected projection. ## Appendix E — Superseded and Retained Principles The previous interpreter UI draft remains useful design history. The new specification retains its requirements for: - domain-first concepts; - exact source preservation; - Mention/Referent/Ontology Concept separation; - explicit construct elements and frame roles; - ambiguity and diagnostics as first-class results; - provenance and individual validation checks; - semantic HTML; - stable object addressability; and - locally reachable raw evidence. It supersedes the previous draft's normative preference for: - a long vertically ordered execution narrative; - permanent source dominance; - an asymmetric narrative-and-margin desktop layout; and - a restricted visual grammar that discourages ordinary interactive application structures.