Story 1606: derived/document.md — the markdown the Registrar seam reads

Why this exists (the catastrophe it prevents). Blake — the Registrar agent that classifies a freshly-indexed document (name, type, tags, duplicate?) — takes one field as its raw material: RegistrarDocumentInput.document_markdown. Its prompts assume markdown: heading and paragraph structure is the signal that tells it "this is the title", "this is a clause". But the extraction worker, today, writes exactly two derived artifacts and neither is markdown: text.txt is deliberately plain (it is the literal string fed to to_tsvector, so it must never gain markup or the search vector would diverge), and pages.json is structured JSON for the geometry/highlight UI, not prose. So the seam has a contract hole: the producer never emits the one shape the consumer needs. Without this Story, the Blake broker-consumer (P3b) would have nothing to read, or — worse — we would be tempted to lie and feed plain text as "markdown" (plan Option B), corrupting Blake's structure-dependent classification. This Story closes the hole at the source: synthesize a real document.md from the structure we already captured, at the same terminal transition that writes the other two.

🛰️ Satellite: one terminal transition, now three artifacts

extraction worker — text-bearing terminal transition (processor.py)
   │
   │  pages: Sequence[DocumentPage]   (each page: text + paragraph blocks w/ kind+bbox)
   │  full_text: str                  (page text joined — the search-vector source)
   │
   └─▶ write_derived_artifacts(...)  →  firms/{f}/matters/{m}/documents/{d}/derived/
          ├─ pages.json     application/json            (structured: geometry/highlight)
          ├─ text.txt       text/plain; charset=utf-8   (search-vector source, NOT markdown)
          └─ document.md    text/markdown; charset=utf-8 (NEW — the Blake/Registrar input)   ◀── Story-1606
                              ▲
                 serialize_document_markdown(pages=pages)
                 synthesized from the SAME paragraph blocks behind pages.json

The key shape: document.md is built from the same persisted paragraph blocks that pages.json carries — not a second extraction, not a new model. One terminal transition, one deterministic key per artifact, so a re-run overwrites all three in place (idempotent put_object). Three artifacts, one unit of work, one trace.

✈️ Airplane: the change surface (one file of production code)

🔬 Microscopic: how the markdown is synthesized

The renderer — title every line by its reason. The blocks were captured at paragraph grain by Story-1584's compose_paragraphs; each block carries a kind (the persisted block_type). The renderer maps each block's kind to a markdown construct, in document order:

def serialize_document_markdown(*, pages):
    segments = []
    for page in pages:                       # document order — pages already ordered
        blocks = page.blocks or []
        if blocks:
            segments.extend(                 # render each block by its kind...
                seg for block in blocks if (seg := _markdown_segment(block))
            )
        else:
            text = (page.text or "").strip() # ...or fall back to page text when a
            if text:                         #    text-only vendor persisted NO blocks
                segments.append(text)        #    (else the artifact would be empty)
    return "\n\n".join(segments).encode("utf-8")   # blank line = markdown paragraph sep

_HEADING_BLOCK_TYPES = frozenset(
    {"heading", "title", "header", "section_header", "section_heading"}
)

def _markdown_segment(block):
    text = (block.get("text") or "").strip()
    if not text:
        return None                          # drop empty/whitespace blocks, no blank seg
    if block.get("block_type") in _HEADING_BLOCK_TYPES:
        return f"# {text}"                   # heading kinds → ATX heading
    return text                              # paragraph, line, table, ... → plain text
                                             #   (this IS "tables degrade to text")

Three properties the synthesis must hold, and why:

One-sentence recall: the extraction worker now writes a third derived artifact, derived/document.md, deterministically synthesized from the same paragraph blocks behind pages.json (heading-kind → ATX heading, everything else → plain-text paragraph, page-text fallback when a vendor has no blocks), so Blake's document_markdown contract is honestly served without a new dependency or span.