# The Semantic Browser
# Book: Language
# Chapter URL: https://programmer.ie/books/language/13-chapter/
# Prose fingerprint (sha256, normalized): c4c0efe05a629ded3a26d7009053ee7e961f307a55a0b419249f292c0ad56846
# Snapshot generated at build time by Hugo. This is the complete rendered prose
# of the chapter; it is not a transcript of the source file.

Return to the constructed twenty-page incident report from Chapter 1. A database failed on a Tuesday. The report contains a timeline, log excerpts, five candidate causes, and a conclusion that two engineers dispute. A reader might need to decide whether a proposed fix is justified, determine whether another service is affected, or find one timestamp. These tasks do not call for the same representation, and they do not tolerate the same omissions.
The earlier chapters developed pieces of a possible mediation layer. This chapter asks whether those pieces can be assembled into one coherent path without losing the constraints that made each piece defensible. The incident is a worked design case. It is not evidence that such a browser has already improved anyone’s decisions.
Here is the architecture to be tested. The arrows describe proposed data flow, not a compulsory sequence of expensive model calls. A simple lookup may bypass the generative path entirely. In the generative path, checks must occur before a candidate view is released. What a reader later understands or does is a separate outcome. It must be measured. A pre-display checker cannot certify it.
Proposed Semantic Browser path, not a completed integrated system. Pre-display checks cannot certify what a reader will understand. Open full-size diagram. Call the proposed composition a semantic browser. It is a reading environment that can:
retain the source; derive an inspectable interpretation of it; respond to a declared task; choose whether to alter the presentation; and check each candidate transformation before releasing it. It may also offer separately labelled material alongside the view.
The term names a design. It does not name a product with established performance, and it does not claim that the system possesses the author’s meaning. Keeping a source-linked record and passing a gate do not establish either complete source fidelity or improved reconstruction by the reader. The architecture is useful only if those outcomes survive independent tests against simpler alternatives.
From the report to a record First, the report is treated as an identified, versioned source. An interpretation can then be extracted and stored. In the constructed example, that interpretation includes:
five reported candidate causes, each with the evidence its author cites; the sequence of events; the claims attributed to the engineers; and the qualifications attached to those claims. Consider hypothesis three. It can be excluded only if replication lag is below a specified threshold, and the report says the necessary measurement is missing. The record must therefore preserve a conditional exclusion and an unresolved condition together. It must not quietly convert them into a finding.
Every entry points to a particular passage and source version. Relations the source does not clearly support remain marked as candidates or unknown. These links make the reading inspectable, but they do not make it infallible. An extracted record can omit an important claim, misread an exception, or pass one mistake into every downstream view. If the source changes, any interpretation whose link to the source can no longer be re-established becomes invalid.
Next, the reader declares a task before any new view is selected. The obligations depend on that task, and they are recorded before the candidate representation is generated. Suppose a manager must decide whether to approve a proposed fix. She needs enough evidence to challenge the leading explanation, not merely an attractive diagram of it. A task-specific obligation set might look like this:
task: assess whether the proposed fix is justified source: identified incident-report version must remain recoverable: - all five candidate causes and their reported supporting or opposing evidence - who disputes the conclusion and the reasons stated for disagreement - that hypothesis three is excluded only if the lag condition holds - that the required replication-lag measurement is missing - the proposed fix, its author and the stated justification - where each decision-relevant item appears in the unchanged report These obligations are not a summary. They do not claim that the report is correct, and they are not a complete model of the manager’s intent. They are proposed acceptance conditions for one transformation. The system should expose them for inspection, allow unresolved obligations, and record who approved or revised them.
Their adequacy must also be assessed independently. If the source contains a crucial condition that nobody included in the list, a rendering can satisfy every declared obligation and still mislead. Freezing the obligation set before generation prevents the output from quietly redefining success. It does not turn the set into a perfect test.
One source, several tasks The same source version can serve four tasks, and a reusable record can support them where one is needed. What changes from task to task is the omission that is permitted, the form that is useful, and the cost of getting something wrong. Obligations must therefore vary by task, even when the report and its interpretation are shared. The following are proposed behaviours for a browser. They are not four reader outcomes that have already been observed.
Deciding whether to open it. An engineer on another team wants to know whether the incident affects her service. A short preview may be enough, provided it accurately identifies the named services, the relevant failure conditions, and the status of the disputed cause. The preview supports selection, not approval of a fix.
Both kinds of error are costly. A false skip may mean missing something that matters. A false open uses attention and may crowd out other relevant reports. If the source does not reliably identify affected services, the preview should show that uncertainty or fall back to the report. It should not fabricate reassurance.
Approving the fix. The manager needs to compare hypotheses with their evidence and exceptions. A graph may make the five candidate causes and their stated evidence links easier to inspect. A table may line up predictions against observed logs. But an arrow is an assertion, not decoration.
The conditional status of hypothesis three, the missing lag measurement, and the dispute must stay attached to the relevant claims in each view. Evidence that appears in the diagram does not excuse its absence from the table. Every consequential element must link to the record and to the quoted source passage. The manager remains responsible for judging whether the evidence justifies the proposed fix.
Carrying out the remediation. An engineer needs an authorised, current procedure, with its preconditions, exceptions and rollback steps. If the report already presents that procedure clearly, leave it in place. It may help to reveal the conditions alongside each step.
An incident report is not automatically an approved runbook. The system must not turn the reported remediation into an executable instruction, and it must not infer permission to act. The source’s status, version and relevant operational authority matter more than a visually smoother sequence of steps.
Looking up one fact. A reader wants the exact time of failover. The system can search and highlight the quoted passage. It should keep the timestamp, the time zone, and whether the passage records an observation or an estimate. There is no reason to invoke extraction, diagram generation or a language-model answer if direct lookup satisfies the task. The fastest faithful representation may be the unchanged page with one line located.
same versioned source possibly shared, fallible semantic record different task → different preservation obligations choose: unchanged · annotated · generated view Leaving the source unchanged is a first-class output. It is not a failure to generate. The browser should also be able to defer when an obligation is unresolved, when the source is stale, when the necessary evidence is absent, or when the cost of verification exceeds the expected benefit.
The choice itself is an engineering claim. To judge it, we need a baseline in which readers have the unmodified document with competent search and navigation. A generated view should earn its place against that baseline, not merely against a deliberately awkward PDF.
What sits beside the page For the manager, an optional margin could show an earlier postmortem. The margin must identify it explicitly as another document, with its own date and version. The system proposes a scoped relation: this earlier report may contradict hypothesis two under these assumptions; candidate, not confirmed. The reader can open both cited passages and see whether they concern the same environment, period and failure condition.
A second item may restate assumptions already present in the incident report, with each source quote attached. If the manager asks a question, an interactive answer may combine source extracts, retrieved evidence and model inference. These are different origins inside one response. Interactivity does not create a new authoritative category.
Origin and epistemic standing must survive presentation and reuse. The labels should work as follows:
a quotation from the report is marked as quoted; an interpretation is marked as derived; the earlier postmortem is marked as retrieved external material; and any new inference is marked as a model proposal. Attaching a citation does not verify that the cited passage supports the claimed relationship. These labels must persist when an item is copied into notes. A reader should be able to dismiss the margin entirely.
Access is another boundary. A sidecar must not search or reveal reports the reader is not permitted to see. The current reading task does not authorise permanent profiling of the reader.
Checking before showing Before a generated view is released, the proposed design applies a preservation check to that view on its own. The unchanged source remains immediately available. Source lookup does not depend on the generative gate.
The check compares the candidate with the frozen, task-specific obligations and with the source-linked record. It looks at direction, condition, uncertainty and relevant evidence. Checking a bundle only once is unsafe. A valid qualifier in a diagram can mask the same qualifier missing from a table. Passing the gate also does not show that the record itself was complete, or that a real reader will draw the right conclusion.
Suppose a comparison table presents hypothesis three as ruled out, while omitting the condition on replication lag and the fact that its measurement is missing. The row is tidy and misleading. If the checker identifies that omission, the candidate is refused. A bounded repair may restore the condition and its source link. After that repair, the table must be checked again.
If the system cannot demonstrate the required preservation, it returns the unchanged source, with a clear indication that the generated view was withheld. It does not quietly replace the source with a flawed candidate just because a disclaimer would be convenient. These are proposed gate behaviours. They are not a claim that an existing checker can detect all such semantic errors.
The gate must be evaluated as an instrument. It should not be praised simply for having a refusal branch. It needs planted omissions, reversed relations, altered numbers, misplaced qualifiers, and fluent nonsense that repeats the expected words. It also needs faithful views, so that false refusals are counted as well.
Crucially, the gate should be tested on held-out variants, not only on the constructed cases used to repair the checker. Record:
false passes; false refusals; unresolved outcomes; latency; and whether repair introduces fresh errors. A checker that refuses often is not necessarily safe. A checker that rarely refuses is not necessarily useless. Its discriminating performance matters.
Inspecting the communication loop The proposed browser could expose the three observations described in Chapter 8. In brief, the reader can:
inspect the original source; inspect A, its proposed meaning inventory; choose an alternative representation; inspect B, what that representation appears to communicate; and use an observable answer, explanation or decision to propose C. A task-sensitive comparison could identify candidate differences between A and B. It could let the reader correct the interpretation, reject the view, ask for clarification, or return to the original. Feedback would enter the next communication, with its own version and checks.
Take the incident report again. A table might say that hypothesis three is excluded, while the source leaves the lag measurement unresolved. B could expose that change before display. A reader who still answers “the cause is ruled out” supplies another observable claim, and C can assess it. Restoring the qualification repairs the representation. A new answer or decision is then needed to judge whether the repair helped the reader. Neither matching inventories nor a corrected screen establishes internal understanding.
This remains an optional reading path. The fixed original must stay usable without extraction or model calls. The prepared static source, view and correction companion is a curated example, not this full browser. Language Studio separately reports development mechanisms for inspecting communication inventories. That work does not establish the future reader loop on programmer.ie, independent semantic fidelity, or reader benefit. The scripted reference example below keeps its own, narrower standing.
What it costs, and where it can fail Composition introduces costs that isolated examples conceal. Interpretation and checking take time and money. A source-linked record can become stale. A shared extraction error can mislead every view. A sidecar can consume the attention that a diagram was meant to save. Even the right choice of representation can be undermined by a faulty renderer, or by a reader who trusts the margin more than the report.
The costs depend on the task. For a timestamp lookup, the cost of a full pipeline may exceed the whole task. For a disputed causal diagnosis, the cost of overlooking a missing condition may far outweigh a modest delay.
The difficult claim is therefore about the assembled system, not about how clever its parts are. A good relation classifier cannot compensate for a candidate that retrieval never found. A correct semantic record cannot prevent an unfaithful diagram unless the renderer and the gate honour it. A checker can reduce one class of distortion while creating delays or false confidence elsewhere.
The parts must be tested together, against competent non-generative baselines and simpler generative ones. The complete architecture has not been evaluated with real readers in this book. The scripted demonstration below cannot supply that missing evidence.
A proposed end-to-end test The incident report is a useful walkthrough, but it is a poor sole benchmark. The proposed test would begin by freezing a small, varied corpus. It would include constructed reports and reports whose use is authorised, along with verified passages, source versions, disputed claims and deliberately planted failure modes.
Before the experiment, independent reviewers would define each task’s preservation obligations, evidence references and acceptable decisions. A held-out assessment set would be kept separate from the examples used to build the gates. The corpus should include easy single-fact lookups, relevance triage, disputed approvals and procedure interpretation. A browser that wins only on complex diagrams may still lose overall.
The test should compare at least four conditions:
the unchanged report with strong search and navigation; human-authored task views; direct model-generated views with source links; and the proposed semantic-record browser, with its gates and abstention. Where feasible, the record, the checker and the sidecar should be ablated separately. Otherwise a gain could be credited to the whole architecture without identifying the component that produced it. Task order should be counterbalanced across readers. Model versions and task budgets should be held fixed. Outcome adjudicators should be blinded to the interface used. Model-backed runs should be repeated, rather than accepting a single polished sample.
The test should report distinct outcomes:
obligation-level preservation and unsupported additions; false skips on selection tasks; decision correctness on held-out incident questions; time, navigation and interruption burden; helpful and harmful abstentions; checker false passes and false refusals; source-trace accuracy; and production cost. Readers should be asked what they believe before correctness is scored, so that increased confidence in a wrong answer can be observed. Results should be stratified by task and source difficulty. The unchanged source should remain a candidate for every task.
A browser that is more appealing but less accurate, or more faithful but prohibitively slow, has not demonstrated a general advantage. This is a proposed experiment, not an experiment already run.
What the browser does not claim The boundaries established along the way still hold when the pieces are assembled:
source ≠ semantic record ≠ rendering source-linked ≠ faithfully interpreted consistent across views ≠ correct against source retrieved ≠ verified; cited ≠ supported checker passed ≠ intent preserved preference ≠ comprehension ≠ task benefit permission to render ≠ permission to act The record is a revisable interpretation. It is not the report, and it is not a source of truth. A retrieved document has been found, not independently verified. A citation identifies a place to check. It is not proof that the candidate relation holds. A passed preservation check is evidence about the specified obligations only. Reader preference is not comprehension, and comprehension is not effective action.
The source must stay accessible in its actual version. Corrections to the derived record must be logged. No generated view may silently replace an approved document or authorise operational changes. These distinctions are controls that an implementation must enforce. They are not guarantees conferred by the architecture’s diagram.
What has changed The conventional fixed-page path is a useful comparison. Authors, editors and software have long offered more than one view of a text, and readers have never been passive decoders. The simplest picture of that path is this:
AUTHOR → FIXED PAGE → READER The proposed browser inserts a conditional, inspectable mediation path. It does not require generation for every encounter. The following schematic should not be mistaken for a guarantee of understanding:
SOURCE → unchanged view ────────────────────────→ READER ↓ if a new view is useful source-linked interpretation + declared task ↓ preservation obligations + proposed rendering ↓ per-view check → admit / repair / fall back ↓ if admitted task-specific view ────────────────────────────→ READER ↓ outcome still unknown This is one concrete form that the book proposes for intelligence entering the channel: an inspectable choice about whether and how to transform a representation for a current purpose. The system may interpret, route, render, decline or show its evidence. It does not become the author, know the reader’s mind, or gain authority to act.
Communication now has another accountable participant in the middle. That participant can change the evidence from which the reader reconstructs the author’s meaning. Whether the change is a gain must be judged from the source and from the reader’s actual task outcome. The existence of a generated interface is not enough to decide it.
Running it The reference implementation (ernanhughes/project-language) documents npm run example:ch13. This is a scripted demonstration. It uses a shortened, constructed incident report and a hand-written semantic record. It runs with a scripted stand-in for the model on a Pi host and makes no real model call.
The example tests the program’s defined routes and checks under supplied inputs. It is not a real-model extraction experiment, an independent semantic evaluation, or a reader study.
In the documented example, proposed generated views are gated before they appear in the browser view. A structurally invalid document record causes fallback to the source. The script exercises two cases: a repair after refusal, and a bounded sequence that ends in fallback. A view is closed once it is admitted or returned, and only the reader can reopen it. A checker that has not been validated against its supplied reference cannot authorise a generated view. The direct fact-lookup branch returns the source unchanged. The procedure branch adds annotations without rewriting the source text.
These are implemented routing and control rules for the constructed case. They are not proof that real extraction or real readers behave well.
The build also showed why per-view checks matter. Checking a diagram and a table jointly allowed a missing condition in one row to be masked by the diagram, which still included it. The local check was then narrowed to each view and to the relevant row. After review, it was strengthened to require the condition’s wording, the hypothesis evidence, and the arrow direction.
That history is evidence that the implementation catches some constructed errors, and that the earlier checker was inadequate. It is not evidence of coverage against unseen errors. Extraction is still bypassed by a hand-written record. Its completeness, its semantic faithfulness, the checker’s generalisation, its effects on readers, and its end-to-end costs all remain unmeasured.
Where this leaves us, and what it creates Part I has developed a disciplined proposal for representation mediation. A receiver reconstructs meaning from what a representation makes available. A task can justify changing that representation. But a generated view may drop an exception, invert a relation, or amplify an unsupported claim.
A semantic record, typed relations, declared preservation obligations and a checked rendering path make some of those risks inspectable. They do not remove the risks automatically. The Semantic Browser gathers these proposed mechanisms into one testable design. It gives a reason to leave the source alone, and a way to say that a candidate has failed. Its central claim is architectural. The evidence of human benefit has yet to be earned.
The browser suggests a family of views: previews, diagrams, comparisons, annotated sources and optional evidence panels. These are selected for a reader who has already encountered a document. That raises a different problem. Most potentially valuable sources are not open in front of anyone. Conference recordings, newly published papers, incident reports, advisories and conversations accumulate faster than a person can examine them. Generating another form for each source does not decide which source deserves attention. Unlimited generated representations can make overload worse.
Part II therefore changes the question. It moves from what form should this take for the current task? to what should reach the reader at all, why, and when?