\documentclass[11pt]{article}

\usepackage{amsmath,amssymb,amsthm}
\usepackage[margin=1in]{geometry}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage[capitalise,noabbrev]{cleveref}
\usepackage{booktabs}
\usepackage{longtable}
\usepackage{tabularx}
\usepackage{array}
\usepackage{ragged2e}
\usepackage{enumitem}
\usepackage{microtype}
\usepackage{listings}
\usepackage{url}
\usepackage{seqsplit}
\usepackage{tikz}
\usetikzlibrary{arrows.meta,positioning,shapes.geometric,fit,calc}
\usepackage[numbers,sort&compress]{natbib}

\hypersetup{
  colorlinks=true,
  linkcolor=blue!45!black,
  citecolor=green!35!black,
  urlcolor=blue!55!black,
  pdftitle={MDReader as a Reference Application for Categorical Schema Modeling},
  pdfauthor={Matthew Long; The YonedaAI Collaboration}
}

\newtheorem{definition}{Definition}[section]
\newtheorem{protocol}[definition]{Protocol}
\newtheorem{invariant}[definition]{Invariant}
\newtheorem{falsifier}[definition]{Falsifier}
\theoremstyle{remark}
\newtheorem{example}[definition]{Example}
\newtheorem{remark}[definition]{Remark}

\newcommand{\CatDB}{\textsc{CatDB}}
\newcommand{\MDReader}{\textsc{MDReader}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\accepted}{{\normalfont\textsc{accepted upstream}}}
\newcommand{\papercontract}{{\normalfont\textsc{accepted paper contract}}}
\newcommand{\proposed}{{\normalfont\textsc{provisional contract}}}
\newcommand{\absent}{{\normalfont\textsc{absent/open}}}
\newcommand{\nonclaim}{{\normalfont\textsc{nonclaim}}}
\newcommand{\status}[1]{\par\noindent{\normalfont\textit{Evidence status.} #1.}\par}
\newcommand{\Doc}{\mathsf{Doc}}
\newcommand{\Sec}{\mathsf{Sec}}
\newcommand{\Block}{\mathsf{Block}}
\newcommand{\Link}{\mathsf{Link}}
\newcommand{\Task}{\mathsf{Task}}
\newcommand{\Claim}{\mathsf{Claim}}
\newcommand{\Evidence}{\mathsf{Evidence}}
\newcommand{\Decision}{\mathsf{Decision}}
\newcommand{\Requirement}{\mathsf{Requirement}}
\newcommand{\Component}{\mathsf{Component}}
\newcommand{\AgentContext}{\mathsf{AgentContext}}
\newcommand{\Span}{\mathsf{Span}}
\newcommand{\Revision}{\mathsf{Revision}}
\newcommand{\Projection}{\mathcal{P}}
\newcommand{\Overlay}{\mathcal{O}}
\newcommand{\Map}{\mathcal{M}}
\newcommand{\Prov}{\mathcal{V}}
\newcommand{\Violation}{\mathcal{E}}
\newcommand{\Diff}{\mathcal{D}}
\newcolumntype{L}[1]{>{\RaggedRight\arraybackslash}p{#1}}
\newcolumntype{Y}{>{\RaggedRight\arraybackslash}X}

\setlength{\emergencystretch}{4em}
\setlist{itemsep=0.25em,topsep=0.45em}
\raggedbottom
\lstset{
  basicstyle=\ttfamily\footnotesize,
  breaklines=true,
  columns=fullflexible,
  frame=single,
  rulecolor=\color{black!20},
  showstringspaces=false,
  keepspaces=true
}

\definecolor{sourceblue}{RGB}{226,237,249}
\definecolor{overlaygreen}{RGB}{229,243,232}
\definecolor{mappinggold}{RGB}{249,238,211}
\definecolor{warningred}{RGB}{249,228,228}
\definecolor{statusgray}{RGB}{240,240,240}

\title{\MDReader{} as a Reference Application for\\
Categorical Schema Modeling:\\
Typed Markdown Projections, Inspectable Mappings, and Evidence Boundaries}
\author{Matthew Long \\
\textit{The YonedaAI Collaboration} \\
\textit{YonedaAI Research Collective} \\
Chicago, IL \\
\texttt{matthew@yonedaai.com} $\cdot$ \url{https://yonedaai.com}}
\date{23 July 2026}

\begin{document}
\maketitle

\begin{center}
\fbox{\parbox{0.88\linewidth}{
\centering
\textbf{Provisional design and acceptance contract.}\\
The audited repository contains no \MDReader{} package or application result.
}}
\end{center}

\begin{abstract}
Markdown is convenient precisely because it leaves many relationships
implicit. A heading contains paragraphs by position. A claim may cite evidence
in another file. A decision may satisfy a requirement, invalidate a task, or
change an architectural dependency without declaring any of those relations in
a database schema. Search can recover similar passages, but similarity alone
does not expose typed paths, mapping obligations, constraint witnesses,
provenance, or the semantic effect of a revision.

This paper specifies \MDReader{}, a reference application for testing how
categorical schema models could make those relationships inspectable while
ordinary Markdown files remain authoritative. The proposed application
projects a corpus into versioned document structure, layers typed overlays for
claims, evidence, decisions, requirements, tasks, architecture, and agent
context, and exposes mappings among these views. It defines contracts for
object inspectors, path and mapping exploration, migration visualization,
constraint violations, provenance, historical queries, and semantic diffs.
Local execution is specified in terms of transactional SQLite storage, with
optional PostgreSQL synchronization governed by an explicit compatibility and
conflict protocol. Retrieval is deliberately hybrid: lexical, vector, and
typed relationship signals remain distinguishable, and embeddings are never
treated as identity, truth, authority, provenance, or proof.

The contribution is a falsifiable application contract, not an implementation
report. At the audited repository revision, \code{apps/mdreader/} is empty and
has no package history. There is no Markdown parser, user interface, database
backend, server API, search index, provenance executor, semantic-diff engine,
browser suite, or synchronization layer. The accepted upstream computational
boundary covers finite schemas, typed paths, total mappings, finite instances,
and bounded Delta evaluation over a closed fixture corpus. It does not provide
an application or database runtime. We therefore present evaluation protocols
rather than results: seeded end-to-end tasks, retrieval ablations, independent
semantic oracles, accessibility checks against WCAG 2.2, preregistered
usability tasks, storage recovery tests, and optional synchronization failure
injection. Exact nonclaims, dependency status, and twenty falsifiers make clear
what future evidence must establish before \MDReader{} can be called a working
reference application.
\end{abstract}

\tableofcontents

\section{Introduction}
\label{sec:introduction}

\subsection{The gap between finding text and understanding a corpus}

Consider a research repository with a design note, an implementation roadmap,
a release record, and a review. A text search for ``migration'' returns all
four. A vector search may rank two semantically similar passages near the top.
Neither result answers a more precise question: which accepted decision
satisfies requirement R7, through which mapping, at which source revisions,
and what changed when the migration schema was edited?

That question has structure. Files contain sections and blocks. Some blocks
are claims; others are evidence or decisions. A requirement can be linked to a
verification artifact. A mapping can send a source relation to a path through
a target schema. A revision can preserve the text of a heading while changing
the typed object it denotes. A constraint failure should point to a witness,
not merely color a node red.

The \CatDB{} research program studies typed, versioned schemas and mappings.
Its Markdown context proposes a viewer and search system that makes categorical
structure visible without replacing ordinary files with a proprietary
database~\cite{catdbcontext}. The program manifest assigns that application to
Paper 18, with dependencies on categorical foundations, compilation, queries,
migration safety, information loss, provenance, and the Rust
runtime~\cite{catdbmanifest}. The implementation roadmap places the server API
and \MDReader{} in an open future slice~\cite{catdbroadmap}.

That chronology matters. An application paper can easily slide from
``the interface should show a mapping'' to ``the interface shows a mapping.''
This paper does not make that slide. It defines what a reference application
would have to expose and how to test it. The repository audit found no
\MDReader{} package, tracked application file, package manifest, test suite, or
history under \code{apps/mdreader/}. The planned command
\code{npm --prefix apps/mdreader test} exits before testing because
\code{package.json} is absent.

\status{\absent{} for the application; \accepted{} only for the bounded
semantic dependency described in \cref{sec:evidence}.}

\subsection{Why call a proposed interface a reference application?}

A reference application is useful when it forces a semantic design to answer
operational questions. Where does an object come from? Which source span does
an arrow denote? How can a user distinguish a proposed mapping from a
validated one? What does an inaccessible graph conceal? How are historical
results reconstructed? What happens if indexing stops halfway through a
revision?

Here, ``reference'' names a conformance role, not an implementation quality
claim.

\begin{definition}[Reference application contract]
\label{def:reference-application}
A reference application contract is a collection
\[
  \mathfrak{R} =
  (\mathcal{S},\Projection,\Overlay,\Map,\Prov,\Violation,\Diff,\mathcal{Q},
  \mathcal{L},\mathcal{Y})
\]
of source, projection, overlay, mapping, provenance, violation, diff, query,
local-storage, and synchronization interfaces, together with observable
invariants and falsifiers. An implementation conforms only for the capabilities
that pass their native gates against a named version of \(\mathfrak{R}\).
\end{definition}

This definition lets the paper make a concrete contribution before claiming a
product. It also prevents a mock-up, a JSON example, or a passing semantic
library test from being mistaken for end-to-end application evidence.

\subsection{Contributions}

The paper contributes:

\begin{enumerate}
  \item an evidence vocabulary separating accepted upstream computation,
  accepted paper contracts, provisional application requirements, absent
  capabilities, and nonclaims;
  \item a source-preserving projection model for CommonMark or explicitly
  selected Markdown profiles;
  \item versioned typed overlays for claims, evidence, decisions, requirements,
  tasks, architecture, and agent context;
  \item inspector contracts for objects, paths, mappings, migrations,
  violations, provenance, histories, and semantic diffs;
  \item a local SQLite execution protocol and an optional PostgreSQL
  synchronization protocol;
  \item a hybrid retrieval design that explicitly rejects vector similarity as
  semantic authority;
  \item correctness, retrieval, usability, accessibility, performance, and
  synchronization evaluation plans; and
  \item exact dependencies, nonclaims, threats, and falsifiers.
\end{enumerate}

No item in this list is reported as implemented.

\section{Evidence boundary}
\label{sec:evidence}

\subsection{Five labels}

\Cref{tab:evidence-labels} defines the labels used throughout the manuscript.
They appear near capabilities rather than in a single disclaimer at the end.

\begin{table}[ht]
\centering
\caption{Evidence labels. Acceptance of a paper and acceptance of code are
different facts.}
\label{tab:evidence-labels}
\begin{tabularx}{\linewidth}{L{0.25\linewidth}Y}
\toprule
Label & Meaning \\
\midrule
\accepted{} & A bounded CatDB result has native repository evidence and an
accepted release record. \\
\papercontract{} & An accepted manuscript supplies definitions or an
acceptance contract, but not necessarily an implementation. \\
\proposed{} & This manuscript specifies observable future behavior. \\
\absent{} & The audited repository lacks the capability, artifact, or gate. \\
\nonclaim{} & The manuscript explicitly declines a possible interpretation. \\
\bottomrule
\end{tabularx}
\end{table}

\subsection{What the repository contains}

The correction audit used repository base commit
\code{e2f7cd70217e079af70c3e2ccaca14e6f548fd23}, dated 23 July 2026. Its
working tree also contained uncommitted paper work and later Slice 5 candidate
fixtures. The Cargo workspace contains six packages: core identifiers and
errors, an intermediate representation, schema operations, mapping operations,
bounded migration operations, and a CLI. No tracked file exists beneath
\code{apps/mdreader/}; no package manifest or example corpus exists; and the
path has no Git history.

The accepted Slice 4 release is pinned to
\code{056915834fcc2f172a4a72efe3629f4f753e45cf}. Its closed corpus records 33
cases: 29 semantic comparisons, 4 structural comparisons, and zero
disagreements~\cite{catdbslice4}. These computations cover finite schemas,
typed paths, total mappings, finite instances, and a bounded Delta operation.

The current working tree is not that release checkout. Its all-fixtures command
reports 42 cases: the same 29 semantic comparisons, 13 structural comparisons,
and zero disagreements. Nine later Slice 5 candidate fixtures for schema diff
and information-loss analysis account for the larger structural total. Their
presence changes the current corpus, not the accepted Slice 4 release, and
does not supply \MDReader{} application evidence. The current
\code{cargo test --workspace --all-features} run also passes, but only for the
semantic workspace.

Structural cases are important. Schema-diff and information-loss documents can
be decoded and compared structurally without executing their meaning. A future
interface must show that distinction. A polished diagram cannot upgrade
structural compatibility into semantic evaluation.

\subsection{What the repository does not contain}

A focused workspace and lockfile audit found no SQLite or PostgreSQL driver,
Rust HTTP server, browser framework, desktop shell, or Playwright dependency.
Negative dependency search is not a proof about all possible code, but it
agrees with the empty application path and open roadmap status.

\begin{table}[ht]
\centering
\caption{Current capability boundary relevant to \MDReader{}.}
\label{tab:capability-boundary}
\begin{tabularx}{\linewidth}{L{0.31\linewidth}L{0.17\linewidth}Y}
\toprule
Capability & Status & Consequence for this paper \\
\midrule
Finite schemas, paths, mappings & \accepted{} & May define semantic examples
within the accepted profile. \\
Finite instances and bounded Delta & \accepted{} & May be displayed only after
a future API reproduces the accepted library result. \\
Schema diff and information loss & structural only & The interface must not
label decoded shapes as computed analysis. \\
Query IR or compiler & \absent{} & Historical and typed queries are contracts,
not results. \\
SQL, SQLite, PostgreSQL & \absent{} & Storage and sync sections are protocols. \\
Provenance executor & \absent{} & Provenance records are proposed data and
validation surfaces. \\
Server or application API & \absent{} & No library/API equivalence result. \\
MDReader UI and E2E suite & \absent{} & No usability, accessibility, or browser
claim. \\
General Sigma, Pi, or Kan migration & \absent{} & Migration views must display
unsupported operators. \\
\bottomrule
\end{tabularx}
\end{table}

\subsection{Paper dependencies}

The manifest names Papers 1--4, 9, 13, and 15 as dependencies. At the
correction-audit cut, Papers 1--4, 9, and 13 are internally accepted
manuscripts. Paper 15 remains unaccepted. Manuscript acceptance is distinct
from acceptance of an executor, application, or full Rust runtime. In
particular, the accepted migration, integration, provenance, and
information-loss manuscripts do not imply that any corresponding engine
exists.

\begin{longtable}{L{0.10\linewidth}L{0.20\linewidth}L{0.27\linewidth}L{0.32\linewidth}}
\caption{Dependency ledger.}\label{tab:dependencies}\\
\toprule
Item & Status & Permitted dependence & Open condition \\
\midrule
\endfirsthead
\toprule
Item & Status & Permitted dependence & Open condition \\
\midrule
\endhead
P1 & accepted paper & schema, path, and mapping vocabulary & no application
implementation follows from the paper \\
P2 & accepted paper & physical-plan contract and its limits & no accepted P2
vertical slice, query engine, or database backend \\
P3 & accepted paper & typed migration-map definitions and obligations & no
migration executor, loss detector, diff engine, or backend runner \\
P4 & accepted paper & compositional integration contract and safety conditions
& no integration operator, factorization checker, connector, or identity
resolver \\
P9 & accepted paper & information-loss questions and obligations & no accepted
loss-analysis runtime \\
P13 & accepted paper & provenance record and explanation contract & no accepted
provenance executor \\
P15 & provisional paper & potential Rust application boundary & only a bounded
semantic slice is accepted separately \\
Slice 14 & open roadmap & future server and \MDReader{} gates & package, API,
E2E, equivalence, and review artifacts absent \\
\bottomrule
\end{longtable}

If a dependency changes, the corresponding \MDReader{} schema, stored derived
data, and acceptance fixtures must be versioned or invalidated.

\section{Ordinary Markdown as source authority}
\label{sec:source}

\subsection{Profiles, revisions, and spans}

CommonMark supplies a precise core syntax~\cite{commonmark0312}; GitHub
Flavored Markdown adds tables, task-list items, strikethrough, and
autolinks~\cite{gfm}. A real corpus may also contain front matter, mathematical
extensions, HTML, wiki links, diagram blocks, or local conventions. Calling
all of these ``Markdown'' hides meaningful parser choices.

\begin{definition}[Observed source revision]
\label{def:source-revision}
An observed source revision is a tuple
\[
 r = (i, w, p, h, b, \pi, \nu, t, d),
\]
where \(i\) is a stable source identifier, \(w\) a workspace identifier,
\(p\) the observed relative path, \(h\) a content hash, \(b\) the exact bytes,
\(\pi\) a parser profile, \(\nu\) a parser version, \(t\) observation metadata,
and \(d\) parse diagnostics.
\end{definition}

The content hash helps detect byte equality. It is not by itself the human
identity of a document. A file can move without becoming a new intellectual
object, and two copied files can have the same bytes without having the same
role. Identity policy must be explicit and testable.

A span is a half-open byte interval plus derived line and column coordinates:
\[
 s=(r, [a,b), \ell_a,c_a,\ell_b,c_b).
\]
Byte offsets are authoritative for exact recovery from \(b\). Lines and
columns are presentation aids that depend on newline and Unicode conventions.

\begin{invariant}[Source preservation]
\label{inv:source-preservation}
For an observation and projection operation with no separately authorized
write action,
\[
  \operatorname{bytes}_{after}(r)=\operatorname{bytes}_{before}(r).
\]
Every projected node span must resolve to the exact bytes used to derive that
node.
\end{invariant}

\subsection{Projection is derived data}

For a selected parser profile, let
\[
 \Projection_{\pi,\nu}(r) = I_{\mathcal{D}}
\]
produce an instance of a document schema \(\mathcal{D}\). A minimal
\(\mathcal{D}\) has objects
\[
  \Doc,\Sec,\Block,\Link,\Task
\]
and arrows such as
\[
  \Sec \xrightarrow{\mathrm{document}} \Doc,\quad
  \Sec \xrightarrow{\mathrm{parent}} \Sec,\quad
  \Block \xrightarrow{\mathrm{section}} \Sec,\quad
  \Link \xrightarrow{\mathrm{block}} \Block.
\]
Each object also maps to \(\Span\) and \(\Revision\). Order is explicit rather
than inferred from database row order.

Parse recovery can be useful, but it changes the evidence state. If an
unterminated fence is recovered as one code block, the interface must show the
diagnostic and the profile that produced it. A user should be able to view the
raw bytes alongside the projected node.

\begin{protocol}[Projection conformance]
\label{prot:projection}
A conforming projection suite shall:
\begin{enumerate}
  \item freeze parser profile and version;
  \item include CommonMark examples, selected GFM extensions, and repository
  dialect fixtures;
  \item compare object kinds, hierarchy, order, content, destinations, and
  exact spans to an independent expected-results manifest;
  \item test malformed and recovered syntax;
  \item test Unicode, mixed newlines, large blocks, and embedded HTML;
  \item prove source preservation by pre/post byte hashes; and
  \item retain old projections for historical queries or mark their migration
  explicitly.
\end{enumerate}
\end{protocol}

\status{\proposed{}. No parser, watcher, projection store, or projection
fixture suite is present.}

\section{Typed overlays without hidden rewriting}
\label{sec:overlays}

\subsection{From blocks to assertions}

A paragraph does not announce whether it is a claim, evidence, decision,
requirement, task, or background. A heading hierarchy alone cannot supply that
meaning. \MDReader{} therefore separates source projection from typed overlay.

Let \(\mathcal{O}\) contain objects
\[
\Claim,\Evidence,\Decision,\Requirement,\Task,\Component,\AgentContext
\]
with relations such as
\[
\Evidence \xrightarrow{\mathrm{supports}} \Claim,\qquad
\Decision \xrightarrow{\mathrm{satisfies}} \Requirement,\qquad
\Task \xrightarrow{\mathrm{implements}} \Decision,
\]
\[
\Component \xrightarrow{\mathrm{dependsOn}} \Component,\qquad
\AgentContext \xrightarrow{\mathrm{selected}} \Block.
\]
An overlay instance is not recovered solely by parsing Markdown. It is a set
of versioned assertions anchored to projected objects or spans.

\begin{definition}[Overlay assertion]
An overlay assertion is
\[
 o=(j,\tau,a,\rho,\sigma,q,g,c),
\]
where \(j\) is an identity, \(\tau\) a type, \(a\) source anchors, \(\rho\) its
relations, \(\sigma\) status, \(q\) authority, \(g\) generating activity and
agent, and \(c\) creation and schema-version metadata.
\end{definition}

The status set includes \code{suggested}, \code{reviewed}, and
\code{approved}. It also records \code{rejected}, \code{superseded}, and
\code{invalidated}. The authority field distinguishes an author's assertion, a
reviewer decision, a deterministic extractor, and a model suggestion.

\begin{invariant}[No authority laundering]
\label{inv:authority}
A machine-generated suggestion cannot become an approved overlay merely
because it is displayed, indexed, copied, or used by another machine
operation. The approving transition must identify its actor, input revision,
time, and resulting overlay revision.
\end{invariant}

\subsection{Anchors can go stale}

An exact span may fail after editing. A heading-derived anchor may collide. A
content fingerprint may match copied text. The application should retain
multiple anchor signals and report how an anchor was resolved:

\begin{itemize}
  \item exact source revision and byte span;
  \item stable projected-object identifier;
  \item heading or structural path;
  \item local context fingerprint; and
  \item explicit manual reattachment history.
\end{itemize}

No heuristic reattachment should be silent. A low-confidence anchor is a
violation or review item, not a normal resolved edge.

\begin{example}[A changed requirement]
A roadmap block at lines 120--126 is typed as requirement \(R_7\). The file is
edited, moving the block to lines 133--139 and changing ``may'' to ``must.''
The text-level diff shows the word change. The overlay history shows whether
the old requirement was revised, superseded, or replaced. A semantic diff
then reports which decisions and tasks still claim to satisfy \(R_7\). Merely
finding the new word ``must'' cannot answer that question.
\end{example}

\status{\proposed{}. There is no accepted overlay extractor, editor, authority
workflow, or anchor-repair implementation.}

\section{Mappings as inspectable application objects}
\label{sec:mappings}

\subsection{A mapping must expose its assignments}

Functorial data migration uses mappings between schemas to induce data
migration operations~\cite{spivak2012}. In an application, the first duty is
more modest: show what a selected mapping says and which obligations justify
its status.

For source schema \(S\) and target schema \(T\), a CatDB mapping \(F:S\to T\)
sends source objects to target objects and source arrows to typed target paths.
If
\[
  \mathrm{supports}:\Evidence\to\Claim
\]
is mapped to
\[
  \Evidence
  \xrightarrow{\mathrm{anchor}}\Block
  \xrightarrow{\mathrm{section}}\Sec
  \xrightarrow{\mathrm{documentsClaim}}\Claim,
\]
the user needs the full path, not the vague caption ``evidence maps to claims.''

\begin{protocol}[Mapping inspector]
\label{prot:mapping-inspector}
For mapping \(F:S\to T\), a conforming inspector shall expose:
\begin{enumerate}
  \item identities and versions of \(S\), \(T\), and \(F\);
  \item every object assignment;
  \item every arrow and attribute assignment;
  \item each mapped path with endpoint typing;
  \item source equations and their mapped obligations;
  \item totality, coverage, validation, and execution status;
  \item unsupported or structurally decoded portions;
  \item links to affected source and overlay objects; and
  \item the library, API, and fixture revision behind a computed result.
\end{enumerate}
The normalized record shall be available as structured text. A graph is a
secondary presentation, not a separate authority.
\end{protocol}

\subsection{Graph, table, and path views}

\Cref{fig:mapping-inspector} sketches three synchronized views. The graph
provides orientation. The assignment table exposes completeness. The path
panel explains one selected arrow and its obligation. Selection in any view
must identify the same normalized mapping record.

\begin{figure}[ht]
\centering
\begin{tikzpicture}[
  node distance=7mm and 12mm,
  box/.style={draw,rounded corners,align=left,inner sep=6pt,font=\small},
  arr/.style={-{Latex[length=2mm]},thick}
]
\node[box,fill=sourceblue,text width=0.19\linewidth] (graph)
{\textbf{Schema graph}\\objects and arrows\\selection, not authority};
\node[box,fill=mappinggold,text width=0.22\linewidth,right=of graph] (table)
{\textbf{Assignment table}\\all objects, arrows, attributes\\coverage and status};
\node[box,fill=overlaygreen,text width=0.22\linewidth,right=of table] (path)
{\textbf{Path obligation}\\typed image\\equation or failure witness};
\draw[arr] (graph) -- node[above,font=\tiny,fill=white,inner sep=1pt]{same ID} (table);
\draw[arr] (table) -- node[above,font=\tiny,fill=white,inner sep=1pt]{same record} (path);
\end{tikzpicture}
\caption{Proposed synchronized mapping inspector. No such interface is present
at the audited revision.}
\label{fig:mapping-inspector}
\end{figure}

The graph must not hide parallel arrows, path length, unmapped source
components, or equation failures. Color cannot be the only carrier of status.
A screen-reader user needs a traversable object list, assignment table, and
path sequence with equivalent operations.

\subsection{Computed, validated, and proposed are different states}

A mapping record can pass JSON decoding, pass structural validation, pass
endpoint typing, pass equation obligations, or execute a migration. These
states are not interchangeable. The application should expose a monotone
evidence ladder:
\[
\text{observed} \preceq \text{decoded} \preceq \text{typed}
\preceq \text{validated} \preceq \text{executed},
\]
where an implementation may skip no required evidence while keeping the
higher label. A failed or stale prerequisite invalidates the higher state.

The current accepted semantic slice can validate mappings within its bounded
profile. A future server result would still need to demonstrate that its
normalized request and response match the library computation.

\section{Migration visualization}
\label{sec:migration}

\subsection{Show the operator and evidence status}

Calling every schema change a ``migration'' conceals which operation is meant.
A migration view shall name:

\[
 (S,T,F,\Omega,I_{in},I_{expected},I_{observed},e),
\]
where \(S,T,F\) identify the schemas and mapping, \(\Omega\) is the operator,
the three \(I\)'s distinguish input, expected, and observed instances, and
\(e\) records evidence status.

For bounded Delta in the accepted profile, the view may compare expected and
observed target-shaped data after a future API exists. For Sigma, Pi, general
Kan extensions, physical database migration, SQL generation, transaction
cutover, rollback, or information-loss execution, the current status is
unsupported.

\begin{table}[ht]
\centering
\caption{Fields required in a migration presentation.}
\label{tab:migration-fields}
\begin{tabularx}{\linewidth}{L{0.25\linewidth}Y}
\toprule
Field & Required presentation \\
\midrule
Identity & source schema, target schema, mapping, operator, and versions \\
Scope & selected instance or corpus revision and affected object set \\
Expectation & independently specified expected result or declared absence \\
Observation & normalized computed result with supplying runtime revision \\
Risk & unsupported components, possible loss, failed obligations, and stale
dependencies \\
Comparison & object-level additions, removals, changed values, and witnesses \\
Status & proposed, structural-only, validated, computed, disagreed, or failed \\
Provenance & activity, inputs, software identity, configuration, time, and
review transition \\
\bottomrule
\end{tabularx}
\end{table}

\subsection{Visualization must not simulate execution}

An animation can make a proposed mapping look operational. To avoid that,
unexecuted transitions should use static planned-state conventions and an
explicit label. Sample data generated for explanation must remain distinguishable
from repository data and computed output. If a future animation interpolates
between before and after states, the intermediate frames are presentation,
not database states.

Information loss also requires discipline. The accepted Paper 9 can inform
questions and vocabulary, but the audited runtime has no accepted
loss-analysis executor. The migration view can display a declared risk or an
externally supplied assessment with provenance. It cannot present a computed
loss certificate until a native gate establishes one.

\status{\proposed{} for all application views. \accepted{} is limited to
bounded Delta library and fixture computation, not UI or API execution.}

\section{Constraint violations as records}
\label{sec:violations}

\subsection{A red badge is not a witness}

Validation often collapses to a Boolean or a toast. That is inadequate for a
reference application. A violation must be a versioned record that explains
what failed and points to the data needed to check the explanation.

\begin{definition}[Violation record]
\label{def:violation}
A violation record is
\[
 v=(k,\phi,c,x,w,a,s,\eta,u),
\]
where \(k\) is a stable code, \(\phi\) a phase, \(c\) the constraint identity,
\(x\) the subject, \(w\) a witness or counterexample, \(a\) source anchors,
\(s\) severity and lifecycle status, \(\eta\) supplying runtime and schema
metadata, and \(u\) a human-readable explanation.
\end{definition}

Phases include parsing, projection, schema typing, mapping validation, instance
validation, overlay consistency, provenance completeness, storage, sync, and
presentation accessibility. A repair suggestion is a separate overlay with
its own author, status, and provenance.

\begin{example}[Mapped equation failure]
Suppose a source schema declares \(f;g=h\). A mapping sends \(f;g\) to target
path \(p;q;r\) and \(h\) to \(s\), but the accepted equality profile cannot
establish \(p;q;r=s\). The violation should record the source equation, both
mapped paths, endpoint types, equality procedure and version, and the exact
failure classification. ``Mapping invalid'' is not enough.
\end{example}

\subsection{Lifecycle}

A violation is observed against named revisions. It can be acknowledged,
assigned, resolved, waived, superseded, or invalidated by a dependency change.
Resolution requires a new validation activity; changing the UI state alone
does not resolve the underlying constraint.

\begin{invariant}[Witness fidelity]
Selecting a violation shall expose a witness that independently rechecks the
reported failure against the same normalized inputs. If no compact witness
exists, the record shall say which procedure and logs must be rerun.
\end{invariant}

\section{Provenance and historical reconstruction}
\label{sec:provenance}

\subsection{Provenance is not a tooltip}

PROV-O distinguishes entities, activities, and agents and supplies relations
for derivation, use, generation, association, and attribution~\cite{prov-o}.
Database provenance research further shows how annotations can explain the
contribution of input tuples to query results~\cite{green2007}. \MDReader{}
does not need to claim complete semiring provenance in its first profile, but
it must avoid using the word ``provenance'' for a bare file path.

A minimal result record includes:

\begin{itemize}
  \item source and overlay revision identities;
  \item projection, mapping, query, or validation activity identity;
  \item software revision, configuration, parser profile, and model version;
  \item start and completion time;
  \item generated normalized result and diagnostics;
  \item responsible human, service, or model agent;
  \item review and authority transitions; and
  \item completeness limits and unavailable inputs.
\end{itemize}

\begin{invariant}[Historical reconstruction]
For a result labeled reproducible, the recorded inputs, versions,
configuration, and deterministic seeds shall be sufficient to recompute the
normalized result, or the record shall identify the external dependency that
prevents recomputation.
\end{invariant}

This requirement does not promise byte-identical browser rendering or
deterministic output from an unpinned external model. It demands an honest
account of what can and cannot be reconstructed.

\subsection{Historical queries}

A query result is meaningful only against a corpus and overlay revision. The
query record should therefore bind:
\[
  q=(\text{text or typed request}, R, O, M, C, \theta),
\]
where \(R\) is the source-revision set, \(O\) overlays, \(M\) mappings, \(C\)
constraints, and \(\theta\) retrieval or execution configuration.

Versioning systems such as Decibel and OrpheusDB study dataset branching and
relational version management~\cite{decibel2016,orpheusdb2017}. Those systems
are related design evidence, not \MDReader{} components. The reference
application can begin with immutable logical revisions in local SQLite, but it
must make retention, compaction, branching, and deletion policy explicit.

\status{\papercontract{} for provenance vocabulary; \proposed{} for the
application; \absent{} for a provenance executor and historical-query engine.}

\section{Semantic diff}
\label{sec:diff}

\subsection{Six layers of change}

A text diff is necessary but not sufficient. \MDReader{} should separate:

\begin{enumerate}
  \item source-byte changes;
  \item parse-tree and span changes;
  \item schema and typed-object changes;
  \item mapping assignment and obligation changes;
  \item overlay and authority changes; and
  \item provenance, constraint, and result invalidation.
\end{enumerate}

Let two application snapshots be \(A_0\) and \(A_1\). A semantic diff is not a
single set subtraction but a structured report
\[
\Diff(A_0,A_1) =
(D_s,D_p,D_\tau,D_m,D_o,D_v,D_r),
\]
with source, projection, type, mapping, overlay, validation, and result
components.

Identity matching is itself evidence. Exact stable IDs are strongest. Path,
heading, content, and neighborhood heuristics may propose matches, but the
report must identify the method and ambiguity. Schema-evolution research
illustrates how frequently real systems change in nontrivial ways
~\cite{prism2008}; it does not solve Markdown identity automatically.

\begin{protocol}[Seeded semantic-diff oracle]
\label{prot:semantic-diff}
A future diff evaluation shall create a corpus pair with independently listed
changes:
\begin{enumerate}
  \item move a file without editing it;
  \item rename a heading while retaining a stable source identity;
  \item split one section into two;
  \item change a claim without changing its evidence;
  \item change a mapping path while preserving endpoints;
  \item introduce and then repair a constraint violation;
  \item approve one machine suggestion and reject another; and
  \item change a parser or schema version without changing source bytes.
\end{enumerate}
The oracle shall specify expected matches, additions, removals, changes,
invalidations, and uncertainty. Precision and recall shall be reported per
layer, not only as a global score.
\end{protocol}

\status{\proposed{}. The current accepted slice structurally compares
schema-diff-shaped fixtures but does not execute semantic diff.}

\section{Local SQLite execution contract}
\label{sec:sqlite}

\subsection{Why a local relational store is a reasonable target}

The source corpus should remain ordinary files. Derived structure still needs
transactional identity, references, history, search, validation state, and
jobs. SQLite is a plausible local reference store because it provides
transactions, relational constraints, and an optional full-text index in one
file~\cite{sqlitetransactions,sqlitefts5}. Plausible is not implemented.

\Cref{fig:local-architecture} separates source authority from derived state.
The database may cache bytes for a revision, but it does not silently replace
the file as authoring authority.

\begin{figure}[ht]
\centering
\begin{tikzpicture}[
  node distance=8mm and 14mm,
  box/.style={draw,rounded corners,align=center,inner sep=6pt,font=\small},
  arr/.style={-{Latex[length=2mm]},thick}
]
\node[box,fill=sourceblue] (files) {ordinary Markdown\\source revisions};
\node[box,fill=sourceblue,right=of files] (parse) {profiled parser\\and projector};
\node[box,fill=overlaygreen,right=of parse] (sqlite) {local SQLite\\derived state};
\node[box,fill=mappinggold,below=of sqlite] (semantic) {CatDB semantic API\\bounded capabilities};
\node[box,fill=statusgray,left=of semantic] (ui) {inspectors, search,\\history, and reports};
\draw[arr] (files) -- (parse);
\draw[arr] (parse) -- (sqlite);
\draw[arr] (sqlite) -- (semantic);
\draw[arr] (semantic) -- (ui);
\draw[arr] (sqlite) -- (ui);
\draw[arr,dashed,bend left=30] (ui.north) to node[above,font=\scriptsize]
{explicit external editor only} (files.south);
\end{tikzpicture}
\caption{Proposed local architecture. The dashed path is not an implicit
write-back feature. None of these application components exists in the
audited repository.}
\label{fig:local-architecture}
\end{figure}

\subsection{Logical tables}

The contract does not freeze a physical schema, but a conforming design needs
equivalents of:

\begin{itemize}
  \item workspace, source, source revision, and source span;
  \item projected object, attribute, relation, and parser diagnostic;
  \item overlay assertion, anchor, relation, status transition, and review;
  \item schema, mapping, assignment, path, equation, and validation;
  \item query, retrieval candidate, rank feature, result, and explanation;
  \item provenance entity, activity, agent, and edge;
  \item violation, witness, acknowledgement, and resolution;
  \item logical application revision and parent relation;
  \item background job, attempt, lease, cancellation, and diagnostic; and
  \item FTS document plus embedding metadata, if those capabilities are enabled.
\end{itemize}

SQLite foreign-key enforcement must be enabled for every connection because
the documented default is disabled~\cite{sqliteforeignkeys}. STRICT tables can
reduce accidental type flexibility where the representation permits
them~\cite{sqlitestrict}. Neither mechanism replaces application invariants,
schema migration, or acceptance tests.

\begin{protocol}[Atomic corpus revision]
\label{prot:atomic-revision}
For a logical revision \(R_n\), the local implementation shall:
\begin{enumerate}
  \item observe and hash the intended source set;
  \item begin a database transaction;
  \item record projection, overlay reattachment, validation, index, and
  provenance updates under a non-visible candidate revision;
  \item either commit the complete candidate and atomically advance the visible
  revision pointer, or roll it back;
  \item retain diagnostics for a failed attempt outside the logical revision;
  and
  \item recover after process termination without exposing a partially
  committed revision.
\end{enumerate}
\end{protocol}

Large indexing work may use smaller physical transactions, but the application
still needs a logical completeness marker. A query must not unknowingly mix
old projections with new overlays.

\subsection{File changes and write-back}

File observation should debounce unstable saves, identify renames separately
from delete/create when justified, and recheck hashes before commit. Symlinks,
ignored files, generated content, submodules, permission failures, and
case-folding behavior require explicit policy.

This contract contains no automatic write-back. If a later application edits
Markdown, it must preview the exact patch, ask for explicit authorization,
check that the source revision has not changed, write atomically, and record
provenance. Those requirements belong to a separate accepted capability.

\status{\proposed{}. No SQLite dependency, schema, migration, or recovery test
is present.}

\section{Optional PostgreSQL synchronization}
\label{sec:postgres}

\subsection{Optional means the local application still works}

A local reference application should remain useful on an airplane, in an
isolated repository, or when a shared service is unavailable. PostgreSQL
synchronization is therefore a negotiated extension, never a prerequisite for
opening, indexing, inspecting, or querying a local corpus.

Logical replication can stream data changes, but PostgreSQL documentation
states that schema definitions are not replicated and that schema mismatch can
stop replication~\cite{pglogical,pglogicalrestrictions}. Conflicts also require
visible handling~\cite{pglogicalconflicts}. A checkbox labeled ``sync'' is not
a protocol.

\begin{protocol}[Synchronization capability]
\label{prot:sync}
Before exchanging data, peers shall negotiate:
\begin{enumerate}
  \item application, storage-schema, projection-schema, and overlay-schema
  versions;
  \item workspace identity and authorization;
  \item synchronization direction and table or object scope;
  \item stable identity and deletion semantics;
  \item conflict detection and resolution policy;
  \item DDL migration order and compatibility window;
  \item retry, deduplication, ordering, and checkpoint behavior;
  \item encryption, credential storage, and audit policy; and
  \item a completeness statement for the resulting local revision.
\end{enumerate}
An incompatible peer shall fail closed without corrupting local state.
\end{protocol}

\subsection{Conflict examples}

Two peers can approve different statuses for the same overlay, reattach an
anchor to different spans, delete and edit the same assertion, or create
different schema versions under one logical name. Last-write-wins may be
appropriate for some cache metadata and dangerous for authority transitions.
The policy should be typed by record class and should retain both inputs in the
conflict record.

Tests must inject connection loss before, during, and after remote commit;
repeat deliveries; out-of-order deliveries; local process termination; schema
mismatch; authorization revocation; and remote constraint failure. After each
test, local operation and provenance reconstruction must still work.

\status{\proposed{} and optional. No PostgreSQL driver, sync implementation,
protocol, or failure-injection result is present.}

\section{Retrieval that is not just vector search}
\label{sec:retrieval}

\subsection{Four distinguishable stages}

Exact terms matter in technical corpora. A commit hash, theorem name, CLI
flag, error code, or schema object may be poorly served by an embedding.
Lexical ranking such as BM25 remains a useful baseline~\cite{robertson2009bm25}.
Approximate nearest-neighbor structures such as HNSW can efficiently produce
vector candidates~\cite{malkov2018}. Rank fusion can combine independent
rankings~\cite{cormack2009rrf}. Typed relationships can then expand from a
claim to evidence, from a requirement to a decision, or from a mapping to
affected paths.

The proposed retrieval path keeps these stages visible:

\begin{enumerate}
  \item exact and lexical candidate generation;
  \item embedding candidate generation with model, version, and source
  revision recorded;
  \item typed relationship expansion under named schema and mapping versions;
  \item filtering, reranking, context assembly, and explanation.
\end{enumerate}

Every result should expose which stage contributed it and why it survived
filtering. Scores from unlike systems need not share a probabilistic meaning.

\begin{invariant}[Similarity has no semantic authority]
\label{inv:vector}
Vector similarity shall not establish object identity, logical implication,
truth, authorship, approval, provenance, constraint satisfaction, or
authorization. It may propose candidates for a separately identified
operation.
\end{invariant}

\subsection{The hybrid hypothesis is falsifiable}

The context design rejects a vector-only product. This paper agrees for
contractual reasons: vector retrieval cannot replace typed inspection and
authority. It does not claim that hybrid ranking always improves relevance. A
frozen ablation might show vector-only ranking equal or superior for a
particular query set. That result should narrow the ranking hypothesis while
leaving the source, mapping, provenance, and constraint contracts intact.

\begin{protocol}[Retrieval ablation]
\label{prot:retrieval}
Evaluate lexical-only, vector-only, typed-relationship-only, and hybrid
configurations against the same corpus revisions and judgments. Report recall
at fixed cutoffs, nDCG, MRR, latency distributions, index size, explanation
accuracy, and provenance-link accuracy. Freeze candidate pools, model versions,
seeds, filters, and tie-breaking. Disclose assessor protocol, missing
judgments, query construction, and multiple-comparison treatment.
\end{protocol}

\status{\proposed{}. No FTS, embedding, relationship expansion, reranker,
judgment set, or retrieval result is present.}

\section{Evaluation program}
\label{sec:evaluation}

\subsection{Correctness before preference}

The first evaluation is a seeded corpus with independent expected results.
Fixtures should include headings, nested blocks, tables, task lists, code,
links, claims, evidence, decisions, requirements, tasks, architecture,
mappings, violations, history, and deliberately malformed syntax.

\begin{table}[ht]
\centering
\caption{Core end-to-end tasks and primary oracle.}
\label{tab:e2e}
\begin{tabularx}{\linewidth}{L{0.39\linewidth}Y}
\toprule
Task & Oracle \\
\midrule
Open source from every projected object & exact revision, byte span, and
expected source bytes \\
Inspect a claim and supporting evidence & independent overlay and relation
manifest \\
Trace a mapping assignment & normalized mapping plus typed path obligations \\
Open a constraint violation & seeded subject, constraint, witness, and source
anchors \\
Compare two revisions & layer-specific semantic-diff manifest \\
Reproduce a historical query & pinned corpus, overlays, configuration, and
normalized result \\
Interrupt indexing & visible revision remains complete; candidate rolls back
or resumes under protocol \\
Disable networking & local corpus remains usable \\
Resolve an optional sync conflict & both inputs, policy, resolution, and audit
record retained \\
\bottomrule
\end{tabularx}
\end{table}

Tests should call the public application boundary and compare results to the
semantic library boundary. Reusing the same code to generate fixtures and
evaluate them creates common-mode confidence, so the expected-results manifest
must be independently reviewed.

\subsection{Visualization validation}

Munzner's nested model separates domain problem, data and operation
abstraction, visual encoding and interaction, and algorithm
validation~\cite{munzner2009}. \MDReader{} should use the same discipline:

\begin{itemize}
  \item interview and task evidence checks whether mapping and provenance
  questions matter to intended users;
  \item fixture review checks whether document and categorical abstractions
  represent those questions;
  \item controlled tasks test whether graph, table, and path encodings support
  the intended operations; and
  \item profiling tests layout, indexing, diff, and interaction algorithms.
\end{itemize}

A fast force-directed graph does not validate the abstraction. A preferred
color palette does not establish task effectiveness.

\subsection{Usability protocol}

ISO 9241-11 frames usability through effectiveness, efficiency, and
satisfaction in a specified context of use~\cite{iso9241}. A future study
should preregister:

\begin{itemize}
  \item participant population and relevant Markdown, database, and category
  theory experience;
  \item recruitment, compensation, sample size rationale, exclusions, and
  stopping rule;
  \item frozen tasks, datasets, training, counterbalancing, and baseline order;
  \item a plain file and text-search baseline, a conventional Markdown or
  vector-search baseline, and the conforming application;
  \item primary completion and critical-error endpoints;
  \item secondary time, navigation, confidence, and satisfaction endpoints;
  \item missing-data and multiple-comparison treatment; and
  \item debriefing, anonymization, and artifact release.
\end{itemize}

The System Usability Scale can provide a compact descriptive measure
~\cite{brooke1996sus}. It cannot replace observed task completion or establish
why a mapping was misunderstood.

Potential tasks include finding the evidence for a claim, deciding whether a
requirement has an accepted verification, tracing a mapping path, explaining a
violation witness, and identifying the semantic effects of a revision. The
acceptance criterion should be fixed before data collection. A failed
criterion is a result, not a reason to relabel the study exploratory after the
fact.

\subsection{Accessibility protocol}

The target is WCAG 2.2 level AA~\cite{wcag22}. WAI-ARIA patterns can guide
specific widgets, but native HTML semantics are preferred where possible
~\cite{aria-apg}. Required checks include:

\begin{itemize}
  \item complete keyboard operation and a logical focus order;
  \item visible focus, skip links, landmarks, headings, and named controls;
  \item programmatic table headers and relationships;
  \item contrast, zoom, reflow, text spacing, and reduced motion;
  \item error identification linked to fields and source locations;
  \item announcements for asynchronous indexing and validation state;
  \item no status communicated only by color, position, or animation;
  \item a complete table or structured-text equivalent for every graph; and
  \item manual screen-reader paths through source, mapping, violation,
  provenance, and diff tasks.
\end{itemize}

Automated scanners catch only part of this contract. Results should name
browser, operating system, assistive technology, version, zoom, viewport, and
input mode. Passing a scanner is not a WCAG conformance claim.

\subsection{Performance and recovery}

Local measurements should report cold and warm startup, full and incremental
index time, query latency distributions, memory high-water mark, database
size, write amplification, and recovery time. Corpora should vary in file
count, total bytes, section count, link density, overlay density, mapping size,
and change locality. Hardware, storage medium, power mode, operating system,
SQLite version, cache policy, and background load must be disclosed.

Synchronization evaluation adds offline duration, backlog, conflict density,
round trips, retries, remote version, and network impairment. A local
reference result must not be generalized to universal scale or production
availability.

\section{Acceptance matrix}
\label{sec:acceptance}

\Cref{tab:acceptance-matrix} turns the design into staged gates. Each row can
be accepted or rejected independently. An application release must publish
the matrix with exact source and artifact hashes.

\begin{longtable}{L{0.15\linewidth}L{0.29\linewidth}L{0.30\linewidth}L{0.12\linewidth}}
\caption{Proposed native acceptance matrix.}\label{tab:acceptance-matrix}\\
\toprule
Capability & Required artifact & Decisive gate & Now \\
\midrule
\endfirsthead
\toprule
Capability & Required artifact & Decisive gate & Now \\
\midrule
\endhead
Source observation & watcher and revision fixtures & byte-preservation,
rename, partial-save, and failure tests & absent \\
Projection & pinned parser/profile and expected AST & exact object, hierarchy,
order, and span comparison & absent \\
Overlays & schema, authority workflow, anchor fixtures & no authority
laundering; stale-anchor detection & absent \\
Inspectors & normalized records and UI & every field, path, status, and source
anchor reachable in text and graph paths & absent \\
Mapping & public API plus library comparison & total assignments, typed paths,
obligations, and API equivalence & absent \\
Migration & supported-operator registry and fixtures & expected/observed
separation and unsupported-state fidelity & absent \\
Violations & seeded constraints and witnesses & recall of all seeds and
independent witness replay & absent \\
Provenance & entity/activity/agent records & historical reconstruction and
declared completeness & absent \\
Semantic diff & paired corpora and layer oracles & per-layer precision and
recall with ambiguity disclosed & absent \\
SQLite & migrations, schema, recovery harness & one transaction per logical
revision; foreign-key enforcement; versioned upgrade and downgrade policy &
absent \\
Retrieval & judgments and four configurations & frozen ablation with
explanation and provenance accuracy & absent \\
Accessibility & browser UI and test record & automated plus manual keyboard
and screen-reader tasks & absent \\
Usability & preregistration and anonymized data & fixed task criteria and
reported failures & absent \\
PostgreSQL sync & negotiated protocol and fault harness & conflicts, retries,
DDL mismatch, auth revocation, and local continuity & absent \\
Review & exact source range and native logs & independent review closes
blockers and majors & absent \\
\bottomrule
\end{longtable}

The program roadmap proposes commands for application unit tests, browser
end-to-end tests, API contracts, library semantic equivalence, cancellation and
atomicity, workspace authorization, and application/API comparison. At the
audited revision, those commands are intentions rather than runnable gates.

\section{Threats to validity and security}
\label{sec:threats}

\subsection{Semantic threats}

\paragraph{Dialect ambiguity.}
CommonMark and GFM do not cover every repository extension. A parser can be
correct for one profile and wrong for the corpus. Profiles and diagnostics
must be stored with projections.

\paragraph{Identity drift.}
Paths, headings, and content hashes each fail as universal identity. Stable IDs
and heuristic reattachment require explicit lifecycle rules and conflict
presentation.

\paragraph{Extraction error.}
Claims, evidence, decisions, and requirements are interpretive types. Automatic
classification can be useful as suggestion but can create false authority.

\paragraph{Shared implementation and oracle.}
If the UI, API, library, and fixtures derive from one normalization bug, they
may agree incorrectly. Independent expected results and adversarial cases
reduce this common mode.

\paragraph{Bounded category profile.}
The accepted runtime uses finite, executable structures. Nothing in this
application contract proves general categorical constructions or extends the
accepted equality profile.

\subsection{Storage and synchronization threats}

SQLite constraints do not help if foreign keys are not enabled on each
connection. Transactions do not create a complete logical revision unless
visibility is managed across batches. Crash recovery can retain an apparently
valid but stale search index.

Optional synchronization adds authentication, authorization, confidentiality,
integrity, availability, replay, deletion, and tenancy risks. Logical
replication is not a substitute for application conflict policy. Repository
content may include secrets or personal data; indexing and embeddings can
increase exposure. A production system would require a separate threat model,
data retention policy, secret scanning, encryption design, and security
review. This paper provides none of those results.

\subsection{Evaluation threats}

Seeded tasks can favor the design. Small expert samples can conceal
learnability problems. Familiarity can favor a text-search baseline or the new
interface. Relevance judgments can be incomplete. Accessibility results can
vary across browser and assistive-technology combinations. Performance can be
dominated by corpus shape and cache state. The protocols therefore require
frozen baselines, disclosed participant experience, independent oracles, raw
measurements, and narrow conclusions.

\section{Falsifiers}
\label{sec:falsifiers}

The following observations reject or narrow conformance. They are not a list
of hypothetical bugs to dismiss after implementation.

\begin{enumerate}
  \item A read-only observation, index, search, or inspection action changes
  source bytes.
  \item A projected span fails to resolve to the asserted bytes and source
  revision.
  \item Recovered syntax is presented as a lossless parse.
  \item Stable document identity changes solely because the file moves.
  \item A generated suggestion is displayed as reviewed or approved without an
  authority transition.
  \item An inspector disagrees with the normalized record or the public API.
  \item A mapping view hides an unmapped object, path image, or failed
  obligation.
  \item A structurally decoded artifact is labeled validated or executed.
  \item A seeded constraint violation is missing or exposes an invalid witness.
  \item A seeded semantic change is absent from its required diff layer.
  \item Provenance cannot identify the source revision, transform, software
  identity, configuration, and generated result.
  \item Vector similarity establishes identity, truth, authority, proof,
  constraint satisfaction, or authorization in any application path.
  \item Interrupted indexing exposes a partially committed logical revision.
  \item Local corpus operation requires a PostgreSQL connection or network.
  \item Synchronization silently loses, duplicates, or misattributes
  authoritative data.
  \item A normalized API result differs from the accepted library result for
  the same request.
  \item A graph-only task has no complete keyboard and screen-reader
  equivalent.
  \item The workflow misses its preregistered primary usability criterion.
  \item A reported result cannot be reconstructed from pinned code, corpus,
  configuration, and disclosed external dependencies.
  \item An upstream schema or mapping contract changes while derived state
  remains labeled current without migration or invalidation.
\end{enumerate}

A vector-only ranking win is a narrower falsifier. It rejects a hybrid
superiority claim for that evaluation, but it does not make vector similarity
a mapping, a provenance relation, or a constraint witness.

\section{Exact nonclaims}
\label{sec:nonclaims}

At the audited revision, this paper does not claim:

\begin{itemize}
  \item an implemented \MDReader{} package, user interface, backend, server API,
  or end-to-end test;
  \item SQLite storage, FTS5 indexing, PostgreSQL synchronization, or conflict
  handling in \CatDB{};
  \item a working Markdown parser, file watcher, typed overlay engine,
  inspector, mapping explorer, migration view, provenance view, semantic-diff
  engine, or historical-query engine;
  \item hybrid retrieval superiority or vector-search inadequacy for every
  corpus;
  \item universal CommonMark, GFM, or repository-dialect compatibility;
  \item correct automatic extraction of claims, evidence, decisions,
  requirements, tasks, architecture, contradictions, or entailments;
  \item that embeddings encode truth, identity, authorship, authority,
  provenance, constraints, or permission;
  \item complete provenance, executable information-loss analysis, or
  executable semantic diff;
  \item Sigma, Pi, general Kan extension, arbitrary data migration, physical
  migration, SQL generation, transaction cutover, rollback, or zero data loss;
  \item production scale, latency, durability, availability, security,
  privacy, or multi-tenant isolation;
  \item usability, accessibility, WCAG conformance, responsive-browser
  support, or assistive-technology compatibility;
  \item a categorical theorem, formal verification, or a general Rust/Haskell
  equivalence theorem; or
  \item acceptance of Paper 18 or Paper 15, Slice 14, an application review, an
  accepted PDF, or a publication-ready result; the accepted Papers 3 and 4 do
  not establish application code.
\end{itemize}

\section{Related work}
\label{sec:related}

Functorial data migration supplies the categorical background for deriving
data movement from schema mappings~\cite{spivak2012}. This paper does not
extend that theory. It asks what an application must show so that a user can
inspect a mapping and tell which operations are actually supported.

Provenance semirings provide a rigorous account of how inputs contribute to
query results~\cite{green2007}; PROV-O provides an interoperable vocabulary for
entities, activities, and agents~\cite{prov-o}. The proposed provenance
profile is intentionally smaller than a claim of complete query provenance.
It focuses first on source, transform, software, configuration, authority, and
result reconstruction.

Decibel and OrpheusDB study versioned relational datasets
~\cite{decibel2016,orpheusdb2017}. PRISM and related schema-evolution work
motivate explicit change management~\cite{prism2008}. \MDReader{} differs in
placing ordinary Markdown sources, parser projections, typed overlays,
categorical mappings, and application evidence in one inspection contract.
That difference is a design target, not a comparative performance result.

BM25, HNSW, and reciprocal-rank fusion represent distinct retrieval tools
~\cite{robertson2009bm25,malkov2018,cormack2009rrf}. The proposed design keeps
their signals separate and adds typed relationship expansion. It makes no
novel ranking claim without the ablation in \cref{prot:retrieval}.

Finally, visualization validation, ISO usability concepts, SUS, WCAG 2.2, and
WAI-ARIA practices shape the evaluation contract
~\cite{munzner2009,iso9241,brooke1996sus,wcag22,aria-apg}. Citing these
standards does not confer usability or accessibility. Only an implemented,
tested interface can supply that evidence.

\section{Roadmap to a result-bearing paper}
\label{sec:roadmap}

A result-bearing revision should proceed in dependency order.

\begin{enumerate}
  \item Freeze a versioned source/projection/overlay contract and publish a
  small independent corpus oracle.
  \item Add an application package and lockfile without expanding the accepted
  semantic claims.
  \item Implement local SQLite migrations, connection policy, logical
  revisions, and failure recovery.
  \item Expose the accepted semantic library through a versioned API and prove
  normalized library/API equivalence on accepted and adversarial fixtures.
  \item Add source, object, path, mapping, violation, provenance, and diff
  inspectors with complete textual equivalents.
  \item Implement retrieval stages separately, record explanations, and run
  the frozen ablation.
  \item Run browser end-to-end, keyboard, screen-reader, reflow, and responsive
  checks.
  \item Preregister and run the usability study.
  \item Add PostgreSQL sync only after local correctness, then publish conflict
  and failure-injection evidence.
  \item Obtain independent native review over the exact source range and
  resolve blockers before changing the manuscript status.
\end{enumerate}

Each step should add evidence to the acceptance matrix. It should not
retroactively reinterpret a previous absence as success.

\section{Conclusion}
\label{sec:conclusion}

A Markdown corpus can be easy to read and still be hard to reason about.
Search retrieves passages. It does not, by itself, show whether an evidence
item supports a claim, whether a decision satisfies a requirement, whether a
schema mapping preserves an obligation, or which results a revision
invalidates. Those questions need typed structure, visible mappings, witnesses,
and provenance.

\MDReader{} is specified here as the application that would force those
semantics into contact with ordinary work. Source files remain authoritative.
Projections and overlays are versioned derived data. Inspectors expose complete
assignments and statuses. Migration views distinguish expected from observed
results. Violations carry witnesses. Semantic diffs report change by layer.
SQLite supplies a proposed transactional local store; PostgreSQL sync remains
optional and protocol-bound. Lexical, vector, and typed retrieval signals stay
separate, and similarity never becomes semantic authority.

The repository does not yet contain that application. It contains an accepted,
bounded semantic core and a roadmap item for the server and UI. The correct
conclusion is therefore neither that \MDReader{} works nor that categorical
schema modeling has been validated by a user interface. The result of this
paper is a conservative acceptance target: observable contracts, exact
nonclaims, and falsifiers against which a future implementation can fail
clearly or earn a narrower, evidence-backed claim.

{\small
\bibliographystyle{plainnat}
\bibliography{references}
}

\appendix

\section{Repository audit commands}
\label{app:audit}

The following commands establish the application absence and current semantic
boundary without modifying the worktree:

\begin{lstlisting}[language=bash]
git show -s --format='%H %P %cI %s' HEAD

find apps/mdreader -mindepth 1 -print
test -f apps/mdreader/package.json
git ls-tree -r HEAD apps/mdreader
git log --all --oneline -- apps/mdreader

npm --prefix apps/mdreader test

cargo metadata --no-deps --format-version 1 |
  jq -r '.packages[].name'

cargo test --workspace --all-features

cargo run -p catdb-cli -- \
  fixtures compare fixtures/cases \
  --left rust \
  --right haskell \
  --capability-set slice-4
\end{lstlisting}

The observed application test command exits 254 with \code{ENOENT} for the
\code{package.json} expected under \code{apps/mdreader/}. At the accepted
Slice 4 release source, the closed-corpus comparison ends:

\begin{lstlisting}
summary left=rust right=haskell capability_set=slice-4
total=33 semantic-compared=29 structural-compared=4 disagreements=0
\end{lstlisting}

At the correction-audit working tree, the same all-fixtures command ends:

\begin{lstlisting}
summary left=rust right=haskell capability_set=slice-4
total=42 semantic-compared=29 structural-compared=13 disagreements=0
\end{lstlisting}

The extra nine structural comparisons come from later Slice 5 candidate
fixtures. They do not revise the accepted Slice 4 result.

The complete commands, hashes, expected results, and interpretation limits are
recorded in \code{reproducibility.md}.

\section{Minimum result manifest}
\label{app:result-manifest}

A future result release should publish one machine-readable manifest with at
least:

\begin{lstlisting}
{
  "contract_version": "...",
  "source_commit": "...",
  "application_package_hash": "...",
  "lockfile_hash": "...",
  "catdb_runtime_commit": "...",
  "corpus_revision": "...",
  "parser_profile": "...",
  "projection_schema_version": "...",
  "overlay_schema_version": "...",
  "storage_schema_version": "...",
  "capabilities": {
    "projection": "accepted|rejected|absent",
    "mapping_inspector": "accepted|rejected|absent",
    "bounded_delta_view": "accepted|rejected|absent",
    "semantic_diff": "accepted|rejected|absent",
    "sqlite_local": "accepted|rejected|absent",
    "postgres_sync": "accepted|rejected|absent"
  },
  "native_gate_artifacts": ["..."],
  "accessibility_record": "...",
  "usability_preregistration": "...",
  "retrieval_ablation": "...",
  "review_record": "...",
  "known_failures": ["..."]
}
\end{lstlisting}

The manifest is illustrative, not a current repository schema. Its purpose is
to make a release's evidence boundary mechanically visible.

\section{Author evidence snapshot}
\label{app:hashes}

{\small
\begin{longtable}{L{0.31\linewidth}L{0.60\linewidth}}
\caption{Correction-audit evidence hashes.}\label{tab:author-evidence}\\
\toprule
Artifact & SHA-256 \\
\midrule
\endfirsthead
\toprule
Artifact & SHA-256 \\
\midrule
\endhead
root \code{Cargo.toml} &
\texttt{\seqsplit{8d639b43fd8806b8b8a5341c86af626d95cc2bb68ed85d9074c1722caea40a34}} \\
root \code{Cargo.lock} &
\texttt{\seqsplit{117abb87d3ec22ebfd2ce0f97f80f373b72043601b79464fb259de192c2b9643}} \\
Slice 4 release record &
\texttt{\seqsplit{afe1f08544ffb80b9dadd017a721371292599b863a5e06d92a231f2c90599254}} \\
Slice 4 review record &
\texttt{\seqsplit{69664f8f17cbac5a84b36e819c942bb2a26aa10b8ff00c8cd94914543c6289af}} \\
context file 01 &
\texttt{\seqsplit{89dbe785d84f2ec25819fb8d9b3ccc07fa6b45841c17e97f56de6c19978e11ea}} \\
paper manifest &
\texttt{\seqsplit{bc6cdb5fa6ca411181db8d4a42ecdba47d4542b2615052aaa6c1802f4eb8417a}} \\
implementation roadmap &
\texttt{\seqsplit{66f9c612e6d26790da05923110f7ba1339d1556efe3fa8a4ab65f7bfb75a40af}} \\
verification status &
\texttt{\seqsplit{3a988f61be0f757f54c0aacc2e7065faf5e7ef10d593a0b93aa922ed8156e648}} \\
\bottomrule
\end{longtable}
}

Final manuscript and PDF hashes belong in the separate reproducibility record
after an isolated build and page inspection.

\section{Inspector field checklist}
\label{app:inspectors}

\begin{longtable}{L{0.18\linewidth}L{0.37\linewidth}L{0.34\linewidth}}
\caption{Minimum fields per inspector.}\label{tab:inspector-checklist}\\
\toprule
Inspector & Identity and structure & Evidence and limitations \\
\midrule
\endfirsthead
\toprule
Inspector & Identity and structure & Evidence and limitations \\
\midrule
\endhead
Source & workspace, stable source ID, path, revision, hash, parser profile,
span & diagnostics, observation activity, unavailable bytes, identity method \\
Projected object & object ID, type, parent/order, attributes, source span &
parser version, recovered state, old projection versions \\
Overlay & overlay ID/type, anchors, relations, status, schema version &
author/generator, authority transition, stale-anchor state \\
Path & source object, arrow sequence, target object, attributes & endpoint
typing, normalization procedure, unsupported equality \\
Mapping & source/target schemas, all assignments, equations & coverage,
validation level, structural-only parts, runtime revision \\
Migration & schemas, mapping, operator, input, expected, observed & support
profile, disagreements, possible loss, provenance \\
Violation & code, phase, constraint, subject, witness, anchors & severity,
lifecycle, supplying runtime, repair suggestion authority \\
Provenance & entities, activities, agents, edges & completeness boundary,
external dependencies, reproducibility status \\
Diff & compared snapshots, identity matches, layer changes & match method,
ambiguity, invalidated results, unsupported semantics \\
Query & request, corpus/overlay revisions, filters, candidates, ranking &
model/index versions, stage contributions, explanation, missing judgments \\
\bottomrule
\end{longtable}

\end{document}
