Description

Annotated speech corpora circulate between tools. A corpus is transcribed in one software, aligned in another, analysed in a third, archived in a fourth. Each of these tools defines its own file format, and each format embodies a particular view of what an annotation is: a label on a point in time, a labelled interval, a hierarchy of tiers, a document carrying metadata. No format is a superset of the others. Moving annotations from one tool to another is therefore not a matter of translation, but of transposition: what the source expresses and the destination cannot hold has to be left behind.

This asymmetry is rarely visible to the people who depend on it. Annotation files are, for most of their users, opaque: opening one in a text editor reveals syntax, not structure. The user knows the corpus — the speakers, the tiers, the annotation scheme — but has no direct way to know whether the format they are exporting to is able to carry it. Conversion tools generally answer this by silence: either the operation succeeds, and the loss goes unnoticed, or it fails, and the reason belongs to the internals of the format rather than to anything the user can act upon.

The application "Convert" takes the opposite stance. Its purpose is not only to produce a file in another format, but to make the transposition itself intelligible. What a format is able to hold is stated before the conversion is launched, not discovered afterwards. What a format is unable to hold is expressed as a choice offered to the user, at the moment where the target format is selected, and applied uniformly to the whole set of files. What cannot be transposed at all is reported explicitly, file by file, with its cause.

This stance has a consequence on the shape of the tool. "Convert" operates on sets of files, heterogeneous in format and unknown in content at the time the user makes their decisions. It does not inspect a file in order to propose a tailored treatment; it lets the user state, once, how the annotations are to be written, and applies that decision to every file. The intelligibility "Convert" aims at is therefore not the intelligibility of a particular file, but of the destination format and of what reaching it costs.

"Convert" belongs to the SPPAS ecosystem and relies on its reading and writing capabilities, which cover a wide range of formats used in speech and multimodal annotation. It is available both as a page of the SPPAS Dashboard and as an online application, addressing the same need in two contexts of use: within a working session on a local corpus, or as an occasional service.

Accessibility is treated here as a functional requirement rather than an added quality: the information "Convert" exposes — supported properties, options, statuses — is of no use if it is not perceivable, and the tool is designed accordingly.

Defining the requirements

Requirements

The previous sections state what users need and why; this section states what the system does to answer it, and what it manipulates in order to do so.

Two markers are used throughout. [API-OK] denotes what is achievable with the current SPPAS API. [API-EXT] denotes what requires an extension of that API. A requirement marked [API-EXT] is part of the model; it remains inactive until the API supports it.

Conceptual model

Convert holds no persistent data. Everything it manipulates belongs to one conversion in progress, and is derived from a small number of user decisions. This section states who it exchanges with, which data exist, what produces them, what invalidates them, and on which event each treatment runs.

Organisational model of treatments

One procedure per treatment, numbered as it is. There are two contexts of execution and one organisation: what differs between the local server and uwsgi is who exposes the batch, and nothing of what is done. Convert is served identically by the two, which is why there is one table and not two.

Every procedure ends on the server, and none of them ends in the browser. Three are conversational, and in all three what the browser holds is the gesture: the format clicked, the answer chosen, the box ticked. What that gesture means — which options a format raises, which answers it allows, what is still missing — is knowledge of formats, and the client holds none of it. RO1

PF5 is in nobody's charge here. The batch is exposed by a neighbour in both contexts, and this application reads it. It appears in this table so that the one procedure Convert does not perform is written down, and not passed over in silence. RO5

PF6 is one request, and it is the only long one. The results replace what was shown when it ends; nothing is shown per file while it runs. A batch which takes minutes holds that request for minutes, and this level says so rather than leaving it to be discovered. What would show progress per file is not modelled, and it is the one thing this table leaves to be decided. RO6

What the user acts on

Client-side triggers

• Selecting the destination format
• Cancelling the selected destination format
• Answering an export option
• Setting a general option
• Requesting the conversion to run (triggers T06)
• Requesting a new conversion (resets the decisions)

Selecting a destination triggers T02 and produces the options and the structural loss. This is a server request: the correspondence between properties and options is data of the model, and the client holds no knowledge of formats.

Navigation

Convert is a single page. The conversion is not a pathway in the sense TextCueS gives that word: there are no successive steps, but decisions taken in any order, and one operation which requires them. The page shows the formats, the options derived from the selected one, the general options, and the results once the conversion has run.

From the page:

• one can select and cancel a destination without leaving it;
• one can run a conversion, which replaces the results shown;
• one can start a new conversion, which resets the decisions.

Rules of organisation

• RO1 — The client holds no knowledge of formats. Every derivation is a server request, the correspondence between properties and options being data of the model.
• RO2 — The two contexts of execution are one organisation. What differs is who exposes the batch, never what is done with it, and the two deployments are one implementation.
• RO3 — The decisions are taken in any order. None of them is a step, and none is a precondition of another: only the conversion requires them all.
• RO4 — A decision is never refused because another is missing. What is still missing is said [022], and running is forbidden until it is not [031].
• RO5 — The batch is exposed by a neighbour and read. Convert selects no file, in either context, and alters none [202].
• RO6 — The conversion is one request. The results replace what was shown when it ends, and the failure of one file never ends it [606].
• RO7 — A setting is read and never written. The answer which holds is carried by the page, for this conversion alone [308].
• RO8 — What one conversion has decided is carried between two requests by what the page transmits, and by nothing held on the server. Online, no setting and no session is kept for a given user, and a decision held on the server would be a decision belonging to somebody.

RO8 is what makes the two contexts one organisation: a conversion which keeps nothing on the server is served the same way by a server which knows the person and by one which does not. It is also what T07 rests on — starting again is transmitting nothing rather than undoing something.

What the code holds to

Gathered from the rules of the treatments and from the requirements they answer, and written here once so that each of them has one place and one only. Nothing is added: what follows was already said, and what this chapter buys is that a constraint can be pointed at.

C4 is the one which decides the shape of the code. It is why the correspondence is a file and not a branch, why a property added to the API costs a row, and why ModelFormats is the only class to be read again that day.

C15 and C21 were not in the dossier before the levels below the conceptual were written. The first is what makes the chain of C14 terminate; the second is what makes one implementation serve the two contexts of execution. Both are decisions, and they are written here rather than left to be discovered in the code.

Two constraints are refusals this application accepts rather than avoids. C13 says a batch is never undone, and C23 says what that costs: a file which was refused may have left something where it was to be written, and override is what the next conversion decides on.

The tables

Each class of entities becomes a table, and its identifier becomes its key. Ten tables: five are the knowledge of formats and are permanent, five belong to one conversion and outlive nothing.

The structural loss is a column which is empty. R2 has its low cardinality on the side of PROPERTY, which is (0,1): the table takes the key of OPTION, and it may hold none. A property which a destination does not support and whose option is empty is exactly what that destination cannot hold and no answer can remedy (D9). Nothing counts it and no rule states it: it is read where it stands.

R3 and R9 are aggregations: the aggregated table takes the key of the aggregating one. An answer is named inside its option and two options offer an answer of one name without offering the same answer; a remark is named inside the result which carries it.

R5 and R6 both have their low cardinality on the side of CHOICE, which is (1,1): the table takes the two keys, and the two together identify it. One conversion answers one option once. The same holds of RESULT with R7 and R8: one file of one conversion has one result and no more.

Two tables are read and never written. SUPPORTS is what the API answers, and the table is the shape of that answer, not something this application keeps. BATCH is what the provider of files exposes, read at every request and altered by nothing here [202]. They are written down because the model needs their shape, not because anything of this domain holds them.

Not in the tables, and computed every time they are wanted: the properties of the destination, the options it raises, the structural loss, the answer which holds for an option, the effective default of the preservation option, what is still missing before a conversion can run, and the files which were produced. None of the seven would stay true if it were held, three decisions out of four invalidating them.

Where each table stands

Here the machines are named, and not before. There is no database: three tables stand in the API of SPPAS, two in a file of this application, and five stand nowhere at all.

Five tables stand nowhere between two requests, and that is RO8 written as a place. A conversion is rebuilt from what the page transmitted, used, and dropped. Nothing on the server belongs to anybody, which is what lets one implementation serve a context which knows the person and one which does not.

The correspondence is a file, and that is the whole of « data of the model, not code ». Adding a property to the API adds a row to that file: a property with an option and an answer becomes a question asked; a property with none becomes a structural loss announced. No treatment is written, no branch is added, and nothing of this application is read again.

The converted files stand where the API wrote them. This application does not say where that is, and does not have to: reaching them is asked of what provided them [802].

Operational model of treatments

The organisational level said by what and when; this says in what tasks, and what among them cannot be half done.

One request is one unit. Every request begins by rebuilding the conversion from what the page transmitted, runs the one treatment it was asked for, and sends back what is to be shown. Nothing is begun in one request and finished in another — T06 included, which is long and is one request all the same.

One file is one unit, and the batch is not

The failure of one file never interrupts the others [606], so nothing here holds for the batch as a whole: there is no moment at which a conversion is half done and has to be undone. A file has its result, or it has not been reached yet.

What a failed write left on the disk is the API's, and this application removes nothing. It states a refusal on what the API answered. A file which was refused may therefore have left something where it was to be written, and the general option override is what decides whether the next conversion may replace it. That is a consequence of writing where the user asked, and not a fault of the model.

The chain of remediations ends

A remediation produces a new content which is verified again, so the chain is a loop, and a loop needs a reason to stop. It is this: a remediation is applied at most once for one file. A content which, after every remediation its answers allow, still exceeds what the destination can hold is refused, and the cause reported is the one which ended the chain.

Without that rule, removing empty tiers and splitting a multi-tier file could ask for each other in turn. With it, the chain is as long as the number of options and no longer.

The second write is not a second chance

Anticipation comes first and the typed exceptions are a safety net. The second write happens only on a typed cause for which a remediation exists, and there is no third: a second failure is a refusal. What that costs is bounded — two writes per file at the worst — and what it buys is the file which anticipation did not catch.

Where the code goes

In sppas/ui/swapp/app_convert/. One module per kind of knowledge, and every procedure has one module and one only. The separation this application must keep is the one stated below, and these are its four lines.

What each one promises, which is the reason for the cutting:

• The formats module is the only one which knows what a format holds, and it holds it as data. The day the API gains a property, it is the only one to read again — and what is read again is a file, not a branch.
• Remediation touches no disk: it is given a content and gives back a content. It is where the business logic of this application lies, and it is what can be tested with no file at all.
• The conversion module is the only one which reads and writes files, so it is the only one which meets a typed cause, and the only one to read again the day the API raises another.
• Provision is the only one which speaks to the neighbouring domain. It is given a batch and a way to reach a file, never a path, so there is nowhere here for the place of a converted file to be known.
• Decisions is the only one which knows what the page transmits. It holds no state of its own between two requests, and it is where the invalidation is done: what was derived from a decision which changed is not rebuilt.
• Presentation decides nothing. What it shows was decided before it was called, and the JavaScript it carries renders and nothing else.

The batch is provided, not constituted

Convert does not select files. It receives a batch from its execution context and does not alter it. In a local session, that context is the SPPAS workspace, whose files are checked elsewhere, before Convert is reached: no file selection belongs to Convert. In an online use, the batch results from files brought by the user to the service.

Convert therefore depends on a provider of files, of which it requires only a contract:

• it exposes a set of files, possibly empty;
• Convert reads that set and never modifies it;
• it exists in both contexts of execution.

That component was not designed when this was written, and it is now: it is the provision of files, a service of swapp, and it has its own dossier. Convert is one of the apps it calls A2, and the contract above is what that dossier answers — a workspace holding the files to be treated and them only. What Convert receives is made for it, and the workspace of the person never leaves that domain.

Two things follow, and neither changes the model. What Convert reads is checked elsewhere, so no file selection belongs here [202]; and what it produces is given back to that same service, which is what makes it reachable without the user knowing where it stands [801], [802]. T05 still states a provided batch and not a constituted one, and T08 asks rather than answers.

Implementation model: MVC

• Model: knows the formats, performs T02 and T06, and is the only one which speaks to the provision of files — for the batch (T05) and for reaching what was produced (T08). It is a façade over the SPPAS reading and writing capabilities.
• Controller: identifies the task requested, checks its preconditions, chooses the treatment to run, invalidates the derived data, holds the transient state, calls the model, and prepares the data for display.
• View: renders the state, collects the decisions, triggers the events. No business logic; JavaScript is rendering and interaction support only.

What receives a request is not the controller. The WhakerPy response handles the URL, receives the GET or POST and the events it carries, instantiates the controller, calls it once for that request, and bakes the returned tree — either a full page or an update payload. The controller is called; it does not listen.

The task to run is carried by the request, as an event. The controller reads it and handles it. This holds because Convert has one controller; an application with several would have to dispatch, which is not the case here.

Model

The model is the functional core. It holds the knowledge of formats and the transformation of annotations, and exposes neither to the rest of the application. The façade ConvertModel exposes the single interface the application expects and delegates to three specialised sub-models.

ModelFormats holds the knowledge of formats. It exposes the formats that can be written, their properties, and derives from a destination the options, their available answers, and the structural loss (T02). The correspondence between an unsupported property, the question it raises and the answers available is data it holds, not code it runs: adding a property to the SPPAS API adds an entry, and modifies nothing else. This sub-model reads no file.

ModelRemediation holds the transformations applied to annotations. Given a content and the properties of a destination, it states which remediations the answers require, applies them, and verifies the resulting content against those properties again — a remediation producing a new content, remediations chain, and a chain may end in a refusal. It also states which remediations transformed the content, so that remarks can be attached to the file. This sub-model reads and writes no file: it transforms annotations in memory. It is the place where the business logic of Convert lies, and it is testable on its own.

ModelConversion performs T06. For each file of the batch it reads, calls ModelRemediation, writes, retries once after remediating a typed failure, and produces the result of that file: its status, its remarks, the cause of a refusal. It never interrupts the batch, and one file may produce several converted files.

ModelProvision is the only class which speaks to the provision of files. It exposes the batch that domain holds, and asks it by what each produced file is reached (T08). It is given a way to reach a file and never a path: where a converted file stands is not said by this application C22. It alters nothing of the batch C11, and it is the only place to be read again the day that domain changes.

This structure lets the knowledge of formats, the transformation of annotations, the conversion of files and the dependency on a neighbour evolve separately, behind one stable façade.

Controller

The controller is called once per request, in a stateless context. It initialises an empty state, then rebuilds the current state exclusively from the data transmitted to it. What carries that state is one object, ConvertRecord: the view serialises it at each user action and the controller parses it back, and neither of them holds it between two requests C21. The controller identifies the task requested, checks its preconditions, calls the model, and prepares the data for display.

The controller is also the only one which reads the settings of the application. It takes interoperability from them, hands it to the conversion as the default answer of the preservation option, and writes nothing back: the value is changed for this conversion alone, on the page [308] C20. The model knows no setting, and the view decides nothing.

The controller handles invalidation. Any change of an upstream datum invalidates the data derived from it, which are then neither reused nor displayed: a change of destination invalidates the properties, the options, the answers, the structural loss and the results; a change of an answer, of a general option or of the batch invalidates the results. This invalidation is implicit: only the data explicitly transmitted and recomputed during the current request are used.

Tasks:

• start — transmitted: nothing. Preconditions: none. Triggers: none. Produces: the page in its initial state, with the writable formats and no destination.
• destination — transmitted: the destination. Preconditions: the format can be written. Triggers: T02. Produces: the options, their answers, the structural loss.
• answer — transmitted: the destination, the answers taken so far, and the one just given. Preconditions: the option belongs to the destination, and the answer is one it offers. Triggers: T03. Produces: the answers, and the results invalidated.
• general — transmitted: everything decided so far, and the general option just set. Preconditions: none. Triggers: T04. Produces: the general options, and the results invalidated.
• convert — transmitted: the destination, the answers, the general options. Preconditions: destination defined; batch not empty; every option answered, defaults applying to those left unanswered. Triggers: T06. Produces: the results.
• reset — transmitted: nothing. Preconditions: none. Triggers: none. Produces: the page in its initial state. The batch is not reset: it belongs to the context, not to Convert.

Default answers

An option left unanswered takes a default. Two principles apply, in this order: the default reproduces the current behaviour of the SPPAS API where one exists; failing that, it takes no initiative.

Preservation defaults to yes because that is what the API does today: it writes as comments what a format cannot hold, wherever comments are allowed. Where the destination allows neither comments nor a tier, the option is not offered and the information is lost — which is, again, the current behaviour.

Where a precondition is not satisfied, the controller runs no treatment and states which decision is missing. A decision is never refused because another is missing RO4.

Six tasks for eight treatments, and the two which have none have none for a reason: T02 is triggered by destination and never asked for on its own, and T08 follows the conversion in the same request. Every other treatment is one task, and every task is one request.

The controller is implemented by a single class ConvertController, exposing one entry point handle(request_data).

Views

As in TextCueS, the WhakerPy response builds the whole HTML tree and the structural elements common to the application — head, header, nav, footer — are factored there. The Convert views build only the content of body > main, and of body > script where support scripts are required. They create no structural element, handle no navigation, take no functional decision and perform no linguistic treatment.

Convert has one applicative view, ViewConvert, whose content varies with the data the controller transmits. It is built from five fragments, each with a defined scope.

The shape of these fragments follows from an observation about the users: they do not choose a destination format. They know it already — they are moving to Elan, to Praat, to subtitles — and they come to Convert to reach it. The properties of formats are therefore not there to help decide which format to pick; they are there to state what reaching the one already picked costs. The two are not served by the same presentation, and conflating them is what makes a matrix of formats by properties both indispensable and unreadable.

FragmentFormats presents the formats that can be written, and lets one of them be selected or cancelled. It is a list of extensions, grouped where grouping is possible: the extensions of one piece of software together, the subtitle formats together, the rest as they come. The grouping is heterogeneous by nature — Praat holds three extensions, some formats hold no software at all — and it exists only to let the user find what they came for. This fragment carries no property.

FragmentDestination presents what the selected format holds, and is where the export options are answered. It is an aside: consulting it is not leaving the list. It shows every property, always, in the same order, whatever the format selected. What varies from one format to the next is the state of each line, and whether a decision appears on it. A property has three states, and no more: held; not held, with nothing to decide; not held, with a decision to take. Preservation, covering several properties at once, appears as one line among them.

The stability of that list is what makes it usable. Labels that do not move let the user click from one format to another and see what changed, without reading again. It also answers requirement [104] without hiding anything: a scientific application states its data. Some properties are widely understood — several tiers, media, metadata — and others are specificities that exist almost nowhere but in SPPAS. The latter are made discreet, not absent.

FragmentCompare presents the full matrix of formats by properties, as a details element the user unfolds. This is the one place where formats are compared to one another, which is a legitimate thing to want and a poor way to choose a destination. Unfolded in place rather than opened as a dialog, because comparing is consulting, not deciding: the page stays where it is. Given the room a details element affords, the matrix can here be what it never is when it drives the choice — readable.

FragmentGeneral presents the general options.

FragmentResults presents the result of every file of the batch: its status, the remarks attached to it, and the cause of a refusal. It exists only once a conversion has run. One file of the batch may produce several converted files: the report is not a line per input file.

JavaScript is interface support. It handles local interactions — selecting a format, answering an option, refreshing the aside once a destination is known, refreshing the results — and transmits the state to the server. It holds no business logic and takes no decision on the treatments to run: it knows nothing of formats, of properties, or of what a remediation is. Which options a destination raises is derived by the model, server-side; the client displays what it is given.

The view serialises the current state at each user action. In a strictly stateless context, it transmits to the controller everything the requested treatment needs, without relying on any persistence, client-side or server-side.

The view carries the cross-cutting requirements: contrast, legibility, text alternatives to any graphical encoding, keyboard and screen-reader operation, consistent terminology between the interface and the concepts of the model, explicit messages at every decision point. Convert exposes a technical subject to a non-technical audience; the burden of intelligibility lies entirely here.

The classes

Those which carry the data come from the tables; those which work come from the modules and from the MVC stated above. The names of the working classes are the ones that section fixed, and nothing is renamed here.

What carries the data

ConvertRecord is the class RO8 asks for and which no section named. The view serialises the state at each action and the controller rebuilds it: between the two there is an object, and it is better named than implied. It is what makes the two contexts of execution one implementation.

What does the work

The four sub-models are what the façade holds, and the fourth is ModelProvision: the batch and the way a produced file is reached are asked of a neighbour, and one class is what asks it.

The five fragments — FragmentFormats, FragmentDestination, FragmentCompare, FragmentGeneral, FragmentResults — are classes of the view and build each their own part of body > main. They decide nothing, count nothing and refuse nothing.

What assembles

The response of WhakerPy handles the URL, builds the view and the controller, calls the controller once for that request, and bakes the tree it was given. It is named here ConvertResponseRecipe, and it is the only object of this application anything outside it holds. The controller assembles nothing: it is built, it is called once, and it is dropped.

The class diagram

/ marks what is derived and held by nobody. What the operations promise is the chapter on the contracts; what they are called is a proposal, and one pass renames them all.

Conversion.what_is_missing() is given the batch and does not hold it: what is missing is a destination or a batch which is not empty [031], and the batch belongs to a neighbour. A class which held it would hold what it is forbidden to alter.

ModelRemediation is given a content and gives back a content. It never sees a file, a path or a batch, which is what lets the business logic of this application be tested with nothing installed.

What is tied to what

In yUML

To be read at yuml.me, class diagram.

[ConvertResponseRecipe|bake();_process_events()]++1-1>[ConvertController|record|handle();populate_view()]
[ConvertResponseRecipe]++1-1>[ViewConvert|populate_tree_content()]
[ConvertController]++1-1>[ConvertRecord|task;conversion;to_be_shown|serialize();parse()]
[ConvertRecord]++1-1>[Conversion|destination;override;heuristic;answers;/missing|answer_of();what_is_missing();invalidates()]
[ConvertController]-.->[ConvertModel]
[ConvertController]-.->[ViewConvert]
[ViewConvert]-.->[ConvertRecord]

[ViewConvert]++1-1>[FragmentFormats]
[ViewConvert]++1-1>[FragmentDestination]
[ViewConvert]++1-1>[FragmentCompare]
[ViewConvert]++1-1>[FragmentGeneral]
[ViewConvert]++1-1>[FragmentResults]

[ConvertModel|writable_formats();options_of();structural_loss_of();convert()]++1-1>[ModelFormats|writable_formats();properties_of();options_of();structural_loss_of()]
[ConvertModel]++1-1>[ModelRemediation|remediate();what_was_transformed()]
[ConvertModel]++1-1>[ModelConversion|convert();convert_one()]
[ConvertModel]++1-1>[ModelProvision|batch();reached_by()]

[ModelFormats]-.->[Format|extension;software;properties|holds();can_be_written()]
[ModelFormats]-.->[Option|option;question;answers;default;alters|answers_allowed_by();default_for()]
[ModelConversion]-.->[ModelRemediation]
[ModelConversion]-.->[FileResult|file;status;cause;remarks]

The states

Two things have states in this application, and they are the two the user reads.

Three states and no more. The list of properties does not move from one format to the next: what moves is the state of each line, and that is what makes it readable.

A file has exactly one of the four. What is skipped was never read, and what is refused was: the two are told apart because the user can act on one of them and not on the other.

The sequence, from the first request to the results

1. The page is asked for. The formats which can be written are read, and no destination is defined [012].
2. The batch is read from the provision of files. It is empty, and what is missing is said [203].
3. The user chooses a destination. The request carries it; the controller rebuilds a conversion which holds nothing else.
4. The options that destination raises are derived, their answers restricted to what it allows, and what it cannot hold at all is announced once [501].
5. She answers an option, or leaves it to its default; she sets a general option. Each is one task of its own — answer, general — one request, and each carries back everything decided so far.
6. She asks for the conversion. The preconditions are read on what was transmitted: a destination, a batch which is not empty, an answer for every option.
7. File by file: read, anticipate, write, and at most one second write. Each file has its result, and the failure of one ends nothing.
8. The results replace what was shown: a status for each file, its remarks, and the cause of each refusal, in the words of her data.
9. What was produced is reached, without her being told where it stands.
10. She starts again: the decisions are gone and the batch is not.

Steps 3 to 6 happen in any order, and any of them may happen twice. There is no step which has to come before another, and the only thing which requires them all is step 7.

The error policy

What is raised is caught by the response which answers the request, and by nothing below it. A typed cause of the API is not an error of this application: it is an answer, and it is what the second write is decided on.

How to read them

pre is what has to be true on the way in, and what the operation does not check; post is what the caller can count on without looking. The treatments state their preconditions for one treatment; these state them for one operation, and the two say the same thing at two levels.

What holds everywhere

• What is absent gives back an empty thing — an empty list, no destination, no remark — and never nothing at all.
• Nothing is held between two requests. Every operation is given what it works on and keeps none of it. C21
• Only ModelConversion reads or writes a file of the user. No other class of this application touches a disk.
• Only ModelFormats knows what a format holds, and it holds the correspondence as data. C4
• A view decides nothing: what it shows was decided before it was called.
• What is raised is caught by the response which answers the request, and no class below it writes a catch. A typed cause of the API is not raised to the caller: it is an answer.

Class by class

It reads no file of the user and no content whatever. Every rule of what a destination raises is therefore verified with nothing installed but the API.

It is given a content and gives back a content: no file, no path, no batch. It is where the business logic of this application lies, and it is what can be tested with nothing at all.

It is the only class which meets a typed cause of the API, and the only one to be read again the day that API raises another. What a failed write left on the disk is not removed by it. C23

It is the only class which speaks to that domain, so it is the only one to be read again the day it changes. It is also where C22 stands: nothing here is ever given a path, so no code of this application can show one.

It assembles nothing: it is built by the response, called once, and dropped. A decision is never refused because another is missing.

Where each constraint is held

One place each. A constraint held in two would be a constraint held in neither.

C22 is held by what one operation is not given, which is the strongest way to hold a rule: no code can break it, because no code is handed what it would take to break it. Every one of the twenty-three names exactly one place, C11 excepted, which names two — and they are two halves of one thing: one class reads the batch, another writes nothing into it, and neither can do the other's half.

The models

Twenty-five tests for the four sub-models and the façade. The controller, the view and its fragments are not covered here and are owed.

ModelRemediation, with nothing installed

It is given a content and gives back a content: no file, no path, no batch, and no API to read a format with. It is the business logic of this application, and it is the cheapest thing here to test.

TE4 is the one which would have been forgotten. Nothing in the conceptual model asks for it: it was the operational level which found that a chain needs a reason to stop, and this is that reason checked.

ModelFormats, with the API and no file

TE9 is C4 made checkable. A row is added to the correspondence and an option appears; nothing else in the test changes. The day that assertion has to be rewritten, the correspondence has become code again.

ModelConversion, with a disk

TE20 asserts that something is left behind. It is written that way on purpose: C23 is a renouncement, and a renouncement which is not tested becomes, six months later, a bug somebody fixes.

ModelProvision, against the neighbour

ConvertModel, the façade

What no test covers, and where they stand

• The controller, the view and its fragments. They are owed, and they are what will check that a decision which changed invalidates what was derived from it, that a record parsed twice gives the same conversion, and that a view shows what its record says and nothing more.
• What the API does with the annotations it writes. It is established, it has its own tests or it has not, and this application is answerable for what it asked of it.
• The mockup and the wording. Of the interface, decided against the markup and not against an assertion.

Thirteen of the twenty-five need nothing but the API, six need a disk, two need the neighbouring domain. The cutting into sub-models is what makes that count possible, and the count is what says whether the cutting was worth anything.

They stand beside the code, in the folder of this application.