# Runtime Architecture

This is a thin, deterministic runtime that:

A) ingests Markdown → normalizes a document AST → applies editorial lint (Chicago-derived)  
B) applies typeset tokens/profile (Bringhurst-derived)  
C) renders HTML and PDF deterministically  
D) runs post-render QA gates (widows/orphans, heading keeps, overflow)  
E) generates `layout-report.json` and fails builds when thresholds are exceeded

Primary reference PDFs are used for pointer-based traceability only:

* The Chicago Manual of Style (18th ed).pdf
* Robert Bringhurst – The Elements of Typographic Style.pdf

No bulk transcription is performed; rules are paraphrases and cite sources only by pointer.

## Components

### 1) Registry Loader

Inputs:

* `spec/rules/**.ndjson` (Phase 2 output)
* `spec/schema/rule.schema.json`
* `spec/manifest.yaml`
* `spec/profiles/*.yaml`
* `spec/quality_gates.yaml`

Responsibilities:

* validate each rule against JSON Schema
* enforce ID uniqueness and stable sorting
* build or load indexes in `spec/indexes/*.json`
* compute coverage (implemented vs unimplemented; by enforcement)

Output (in-memory):

* `RuleStore` (rules + indexes + profile overrides + gate thresholds)

### 2) Markdown Ingest + AST Normalization

Design note: initial scaffold will ship with a minimal Markdown parser strategy and can be adapted to the existing Forgejo renderer pipeline.

Degraded mode:

* If parsing fails or structure is missing, switch to minimal node set and mark `structure_confidence: low`.
* Run the “degraded mode contract” from `spec/manifest.yaml`.

### 3) Editorial Lint Engine

* Runs `lint`-enforced rules against normalized AST.
* Emits diagnostics (`lint-report.json`, optional SARIF).
* Autofix is optional and must be deterministic.

### 4) Typeset Profile Engine

* Converts typographic intent into deterministic render inputs (CSS tokens + policies).
* Emits `render.css`, `typeset-report.json`.

### 5) Deterministic Rendering

* HTML generation must be stable (DOM order, IDs, whitespace).
* PDF generation must be deterministic given the same inputs and renderer version.

### 6) Post-render QA Analyzer

Detects:

* widows/orphans
* stranded headings (keep-with-next)
* overfull lines
* table overflow/clipping
* code overflow/clipping
* link wrap incidents

Artifacts:

* `layout-report.json` (canonical QA report)
* `qa-report.json` (gate evaluation + failures)

## Coverage Reporting and CI Guardrails

Coverage is computed from:

* total active rules
* rules with an implemented enforcement handler (lint/typeset/postrender/manual)

CI policy (from manifest):

* fail if MUST coverage drops
* fail if overall implemented coverage drops