import { PAG_LANGUAGE } from "#configuration/constants/code.constants";
import { RATIONALE_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { RATIONALE_SECTION_ID } from "#core/ids/grammar.ids";
import type { Section } from "#types/document.types";

const VOCABULARY_SAMPLE =
    "# code syntax · a structural pattern the model has completed many times\nFOR EACH <item> IN <collection>:\n\n# an english verb · the intent, readable by a person\nANALYZE <held> AGAINST <schema>\n\n# a preposition · the relation between the operands\nREAD <config> FROM <file> INTO <settings>\n\n# together · one line the model completes and a person can review\nEXTRACT <field> FROM <record> INTO <value>";

const SOURCES_DIAGRAM =
    'flowchart TB\n    code["Code syntax · loops, conditions, assignment"]\n    verbs["English verbs · analyze, validate, report"]\n    preps["Prepositions · FROM, INTO, AGAINST, USING"]\n    token["An uppercase token in a fixed slot"]\n    completion["A completion drawn from structured contexts"]\n    code --> token\n    verbs --> token\n    preps --> token\n    token --> completion';

const HONESTY_DIAGRAM =
    'flowchart LR\n    input["Input ambiguity · reduced"]\n    load["Interpretation load · reduced"]\n    variance["Output variance · narrowed, never removed"]\n    claim["The honest claim · tends toward consistency"]\n    input --> load --> variance --> claim';

export const RATIONALE_SECTION: Section = {
    icon: RATIONALE_SECTION_ICON,
    id: RATIONALE_SECTION_ID,
    intro: "The grammar does not change how a model behaves. It changes what the model is completing: an LLM predicts the next token from the patterns it was trained on, and a large share of that training is code, configuration and structured documentation, the three sources <cite>three sources</cite> writes into one line and <cite>vocabulary origin</cite> draws. What that buys is bounded, and <cite>the honest claim</cite> states the bound.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Draw every operative word from the keyword vocabulary and bind its operands with a preposition, so the model completes a recognized structure instead of interpreting a sentence. State the intent in an English verb the reader can review.",
                    boundary:
                        "Structure helps where the model has seen the structure. A vocabulary invented for one project is prose with capital letters, and the model interprets it as it would interpret a sentence.",
                    cause: "The model completes what it has seen most often, and uppercase verbs with explicit prepositions are what it has seen in code, configuration and documentation.",
                    decision:
                        "Reduce ambiguity at the input and verify the output, rather than asking the input to guarantee anything.",
                    failureMode:
                        "A page of careful prose is answered with a confident result that answered a slightly different question, and the difference is invisible until someone runs it.",
                    kind: "lesson",
                    principle:
                        "Explicit high-frequency tokens reduce interpretive variance, and the output stays probabilistic.",
                    problem: "Careful prose is not answered with a more careful result.",
                    validation:
                        "Rewrite one prose instruction as a directive and run both several times against the same gates. The directive passes more often, and where it does not, the gate that fails is the one whose condition was still a judgement.",
                },
                {
                    kind: "text",
                    text: "The vocabulary is a hybrid, code syntax for structure, English verbs for intent, prepositions for the relations between operands, and a line carrying all three is one the model completes and a reviewer reads without a legend.",
                },
                {
                    kind: "text",
                    text: "Token frequency is why the vocabulary is uppercase and closed. A word that appears in the same slot across many structured contexts carries a stable meaning into the completion, and a word that appears in many meanings carries all of them. So the grammar keeps its verbs few, keeps them capitalized, and gives each one a semantic contract stated under instruction patterns. One term for one operation is the ubiquitous language the model and the reviewer share.",
                },
                {
                    kind: "text",
                    text: "Ambiguity reduction sits on the derive stage of the loop: the model derives what a line means, and a line drawn from the vocabulary leaves it one derivation where prose leaves it several.",
                },
                { code: VOCABULARY_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "three sources" },
                { caption: "vocabulary origin", kind: "mermaid", text: SOURCES_DIAGRAM },
                { caption: "the honest claim", kind: "mermaid", text: HONESTY_DIAGRAM },
            ],
            title: "Pattern completion",
        },
    ],
    title: "Why it works",
};