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

const NODE_SHAPE =
    '# a node is the unit · every field is load-bearing, and the gate is what makes it a unit\n# NODE <n> — <NAME>   [<layer> · <axis> · <math type> · yields: <shape>]\n@purpose: "<what this node decides, in one sentence>"\n@axis_question: "<the question its axis asks>"\n@cue: "<the one-line reminder a reader executes>"\n@mandatory                # present on a node of the conative or evaluative layer · it never folds\n\nCONTRACT:\n  input:        <the prior node\'s output, and nothing else>\n  transform:    <what this node does to it, as a chain of semantic operations>\n  constraints:  <what binds the transform>\n  output:       <the one record the next node reads>\n  handoff:      <the condition that closes it, and the shape its decision yields>\n\n# OUTPUT CONTRACT\nSET <output> = <the transform applied>\n\nHANDOFF GATE (evidence-bearing):\n  rule_id: "<NAME>"   yields: <shape>\n  [check] <a claim about the output> (evidence: <what settles it>) over: <the set it ranged over> measured: <n> / <N>\n  [check] <a claim about the output> (evidence: <what settles it>)\n  [check] <a claim about the output> (evidence: <what settles it>)\n  refuse: <the condition that stops it> before <the irreversible write>   # on a node that writes\n  result: pass -> NODE <n+1> | <named failure> -> REPAIR (owner: <the earliest node that can supply the evidence>) | unknown -> BLOCKED';

const DIRECTIVE_SHAPE =
    "# inside a node, a directive is an operation, a target, a relation and a destination · every slot filled\nOPERATION <target> PREPOSITION <source> INTO <destination>\n\nREAD_RESOURCE <records> FROM <store> INTO <held>\nEXTRACT_FACTS <field> FROM <held> INTO <values>\nANALYZE_CONTENT <values> AGAINST <pattern> INTO <findings>\nFILTER <values> TO <kept> WHERE <condition>\nCOMPOSE_ARTIFACT <report> FROM <kept> USING <template>\nPERSIST_ARTIFACT <report> TO <destination>";

const FLOW_SHAPE =
    '# declaration precedes use · a catalogue is data a node reads, a function is a transform it names\nDECLARE <catalogue>: array\nSET <catalogue> = [\n  {id: <member>, asks: "<the question it answers>", yields: <shape>},\n  {id: <member>, asks: "<the question it answers>", yields: <shape>}\n]\n\nFUNCTION <transform>(<input>):\n  DECLARE <out>: array\n  SET <out> = []\n  FOR EACH <item> IN <input>:\n    ANALYZE_CONTENT <item> AGAINST <catalogue> INTO <fit>\n    IF <fit>.<applies>: APPEND {item: <item>, kind: <fit>.<id>} TO <out>\n  RETURN <out>\n\n# branching ends in a colon, iteration names its collection, failure has a recovery\nIF <condition>:\n    EXECUTE_TOOL <next>\nELSE IF <recoverable>:\n    ATTEMPT <retry>\nELSE:\n    REPORT_RESULT "<the blocker, named>"';

const QUESTIONS_DIAGRAM =
    'flowchart TB\n    purpose["What is this for? · the objective, one sentence"]\n    nodes["What does each node decide? · its purpose and its yield"]\n    reads["What does each node read? · only the prior node\'s output"]\n    fails["What can fail, and who repairs it? · the result line"]\n    done["How will I know a node closed? · its gate, with evidence"]\n    write["Then write the document"]\n    purpose --> nodes --> reads --> fails --> done --> write';

const SLOT_DIAGRAM =
    'flowchart LR\n    op["OPERATION · what happens"]\n    target["target · what it happens to"]\n    prep["PREPOSITION · the relation"]\n    source["source · where it comes from"]\n    into["INTO destination · where the result lands"]\n    op --> target --> prep --> source --> into';

export const START_SECTION: Section = {
    icon: START_SECTION_ICON,
    id: START_SECTION_ID,
    intro: "A document is written after five questions are answered, in the order <cite>five questions</cite> draws, and the answers become its parts: the objective, each node's purpose and yield, each node's contract, each gate's result line and each gate's checks with their evidence. Those parts are <cite>node shape</cite>; inside a node each line is <cite>directive shape</cite>, whose slots <cite>directive slots</cite> names, and <cite>catalogue and flow</cite> is what a node declares before it reads. A document written before those answers exist is prose in uppercase.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Answer the five questions before the first line. Write each node with its header, its purpose, its contract, its output and one evidence-bearing gate whose result names the next node and a repair owner. Inside a node, write each directive as an operation, a target, a relation and a destination, with the destination explicit wherever a result must survive the line. Declare a catalogue before a node reads it and name a transform as a function before a node calls it.",
                    boundary:
                        "A one-line task with one input and one output needs one directive and no node. The structure grows with the work, and a document that carries a gate for a single read is ceremony.",
                    cause: "The grammar gives every part of a node and every part of a directive a slot, and a slot left empty is a decision the model makes in the author's place.",
                    decision:
                        "Resolve meaning by position rather than by wording: a slot for every operand, over a fuller sentence around a missing one.",
                    failureMode:
                        "A node says analyze the data and never says into what, so the result exists in the model's reply and nowhere the next node can read it.",
                    kind: "lesson",
                    principle: "A node has a shape and a directive has a shape, and the shapes carry the meaning.",
                    problem: "A line that leaves an operand out reads complete to its author.",
                    validation:
                        "Read each node and name what it reads, what it yields and who repairs its failure; read each directive and name its operation, target, relation, source and destination. A slot with no name is where the model will improvise, and the next node will read nothing.",
                },
                {
                    kind: "text",
                    text: "Meaning is carried by positional slot resolution: a word is read by the slot it lands in. The header's yield slot types the decision the gate owes. The contract's input slot is the discipline: a node reads only the prior node's output, which is what makes the chain checkable. A line that fills every slot leaves the model one completion and the reviewer one reading.",
                },
                {
                    kind: "text",
                    text: "Declaration precedes use because a node reads data by name, so a transform is a walk over a catalogue rather than prose, and a function reads identically in every node that calls it. Control flow is explicit because the model must not infer structure from the order sentences appear in. Iteration always takes the two-word form. Where a failure's recovery is the document's own repair edge, the gate's result line routes it there rather than the branch improvising one.",
                },
                { code: NODE_SHAPE, kind: "code", language: PAG_LANGUAGE, title: "node shape" },
                { code: DIRECTIVE_SHAPE, kind: "code", language: PAG_LANGUAGE, title: "directive shape" },
                { code: FLOW_SHAPE, kind: "code", language: PAG_LANGUAGE, title: "catalogue and flow" },
                { caption: "five questions", kind: "mermaid", text: QUESTIONS_DIAGRAM },
                { caption: "directive slots", kind: "mermaid", text: SLOT_DIAGRAM },
            ],
            title: "Five questions, then the slots",
        },
    ],
    title: "Writing a first document",
};