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

const GRANULARITY_SAMPLE =
    "# too fine · a node per directive, a gate that checks one line ran\n# NODE 1 — READ\n    READ_RESOURCE <config> INTO <held>\n# NODE 2 — PICK\n    SET <name> = <held>.<field>\n\n# too coarse · one node, no recovery point, no gate until the end\n# NODE 1 — EVERYTHING\n    READ_RESOURCE <config> INTO <held>\n    READ_RESOURCE <records> INTO <rows>\n    FOR EACH <row> IN <rows>:\n        COMPOSE_ARTIFACT <shaped> FROM <row> USING <held>.<rules>\n        PERSIST_ARTIFACT <shaped> TO <output>\n\n# bounded · one decision per node, a gate at each boundary\n# NODE 1 — CONFIGURATION   [epistemic · analysis · set-theory · yields: set]\nCONTRACT:\n  input:   <the declaration's objective>\n  output:  <config>, validated\nHANDOFF GATE:\n  [check] <config> read (evidence: the read returned content)\n  [check] <config> conforms (evidence: VALIDATE_ARTIFACT against <schema> passed)\n  [check] <config>.<rules> is non-empty (evidence: a count above zero)\n  result: pass -> NODE 2 | nonconforming -> REPAIR (owner: NODE 1) | unknown -> BLOCKED\n\n# NODE 2 — TRANSFORMATION  [epistemic · formalisation · computation · yields: procedure]\nCONTRACT:\n  input:   <config> from NODE 1, and nothing else\n  output:  <shaped-records>\nHANDOFF GATE:\n  [check] one entry per <record> (evidence: the two counts match) over: <records> measured: <shaped> / <records>\n  [check] every entry conforms to <config>.<rules> (evidence: VALIDATE_ARTIFACT passed on each)\n  [check] <records> unchanged (evidence: a witness read after the transform)\n  result: pass -> NODE 3 | count mismatch -> REPAIR (owner: NODE 2) | unknown -> BLOCKED";

const FLOW_SAMPLE =
    "# NODE 1 — DISCOVERY   [epistemic · analysis · set-theory · yields: set]\n@genesis: existence\nCONTRACT:\n  input:     <the objective's pattern>\n  transform: DISCOVER_RESOURCES \"<pattern>\" INTO <files>\n  output:    <files>\nHANDOFF GATE:\n  [check] <files> is non-empty (evidence: a count above zero)\n  [check] every <file> matches <pattern> (evidence: the discovery's own filter) over: <files> measured: <matching> / <files>\n  [check] no <file> lies outside <root> (evidence: every path prefixed by <root>)\n  result: pass -> NODE 2 | empty set -> REPAIR (owner: NODE 1) | unknown -> BLOCKED\n\n# NODE 2 — ANALYSIS     [epistemic · reasoning · logic · yields: boolean]\n@genesis: difference\nCONTRACT:\n  input:     <files> from NODE 1\n  transform: FOR EACH <file> IN <files>: READ_RESOURCE <file> INTO <content>; ANALYZE_CONTENT <content> AGAINST <pattern> INTO <finding>; APPEND <finding> TO <findings>\n  output:    <findings>\nHANDOFF GATE:\n  [check] every <file> read (evidence: one content per file) over: <files> measured: <read> / <files>\n  [check] one <finding> per <file> (evidence: the two counts match)\n  [check] every <finding> names its <file> (evidence: no finding with an empty source)\n  result: pass -> NODE 3 | unread file -> REPAIR (owner: NODE 2) | unknown -> BLOCKED\n\n# NODE 3 — REPORTING    [evaluative · representation · information-theory · yields: artifact]\n@genesis: structure\nCONTRACT:\n  input:     <findings> from NODE 2 · never anything a later node produces\n  transform: COMPOSE_ARTIFACT <report> FROM <findings> USING <shape>; PERSIST_ARTIFACT <report> TO <destination>\n  output:    <report>\n  freshness: fingerprint(<findings>) + fingerprint(this document)\nHANDOFF GATE:\n  [check] <report> names every entry in <findings> (evidence: each finding's id present) over: <findings> measured: <named> / <findings>\n  [check] <report> persisted (evidence: a read of <destination> returns it)\n  [check] <findings> unchanged since NODE 2 (evidence: a witness read)\n  refuse: <destination> changed since it was read before PERSIST_ARTIFACT\n  result: pass -> TERMINATE | missing entry -> REPAIR (owner: NODE 3) | unknown -> BLOCKED";

const GENESIS_SAMPLE =
    "# a verb realises one stage of how an artifact comes to be\n# and a node never depends on a later stage than the one it realises\nREAD, FIND        -> existence       does it exist, is it found\nANALYZE, FILTER   -> difference      what distinguishes it\nEXTRACT, LINK     -> relation        what it connects to\nCREATE, WRITE     -> structure       how its parts are arranged\nEXECUTE, ITERATE  -> transformation  what operation it performs\nVERIFY            -> constraint      what bounds it\n\n# a genesis inversion · a decomposition defect, not a tie to break\n# NODE 1 — BUILD    COMPOSE_ARTIFACT <base> FROM <signatures>      structure\n# NODE 2 — FIND     DISCOVER_RESOURCES <signatures> INTO <found>   existence · needed by NODE 1";

const BOUNDARY_DIAGRAM =
    'flowchart TB\n    split{"Split here?"}\n    output["The next node needs this node\'s output"]\n    retry["This part is repaired on its own"]\n    human["A person decides before it continues"]\n    persist["The result is persisted before it continues"]\n    verify["A condition must hold before the next node"]\n    combine{"Combine here?"}\n    atomic["The steps succeed or fail together"]\n    partial["A partial result has no value"]\n    shared["The steps share values that must not outlive them"]\n    coupled["Separating adds noise, not clarity"]\n    split --> output\n    split --> retry\n    split --> human\n    split --> persist\n    split --> verify\n    combine --> atomic\n    combine --> partial\n    combine --> shared\n    combine --> coupled';

const FLOW_DIAGRAM =
    'flowchart LR\n    n1["Node 1 · existence · yields files"]\n    n2["Node 2 · difference · reads files, yields findings"]\n    n3["Node 3 · structure · reads findings"]\n    n1 -- gate --> n2 -- gate --> n3\n    n3 -. never a forward reference, never an earlier genesis .-> n1';

export const PHASE_SECTION: Section = {
    icon: PHASE_SECTION_ICON,
    id: PHASE_SECTION_ID,
    intro: "A node is one bounded unit of work with one decision, a declared input, a declared output and a gate at its end; <cite>three granularities</cite> shows the bounded form against the two that fail. Data moves between nodes by name, a value is declared before its first use, its scope reaches every later node, and no node reads an output a later node produces, the flow <cite>contracts in order</cite> writes and <cite>forward flow</cite> draws. Node decomposition is the project stage of the loop: it yields the edges between units, and the order of the nodes is how the artifact comes to be, never a count chosen in advance, the stages <cite>verb to stage</cite> lists; <cite>split or combine</cite> is where a boundary goes.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Give each node one decision and end it with the gate that proves the decision made. Split at a repair point, a persistence, a decision, or a condition the next node needs; combine what succeeds or fails together. Order the nodes by dependency and by genesis, and name in every contract the one prior output it reads and the one output it yields.",
                    boundary:
                        "A document with one decision has one node, and a gate at the end of it is still worth writing.",
                    cause: "A gate can only check what a node produced, so a node that produces several unrelated things has a gate that checks a list rather than a unit.",
                    decision: "Let the boundaries decide the node count, rather than a count decide the boundaries.",
                    failureMode:
                        "A node halfway through a long document fails, nobody can say which earlier output it needed, and the repair restarts from the top because no boundary was a real checkpoint.",
                    kind: "lesson",
                    principle:
                        "Each node is one bounded unit whose data flow to the next is a contract and whose order is a genesis.",
                    problem: "Directives poured into one flat block have no repair point and no place a gate can hold.",
                    validation:
                        "Read each contract's input slot and name the prior node that yields it. A node whose input names nothing from its predecessor is in the wrong place, an input with no producing node is a forward reference, and a node that builds before its input is found is a genesis inversion.",
                },
                {
                    kind: "text",
                    text: "Granularity fails in two directions and both look tidy. Too fine, and each gate checks that one line ran. Too coarse, and the only gate is at the end, where it can no longer say which step failed. The bounded form has high cohesion inside a node and low coupling across the boundary, so the boundary is a repair point and the result line can name its owner.",
                },
                {
                    kind: "text",
                    text: "Node order is a genesis, which is what makes it derivable rather than chosen. A node never depends on an output from a later stage than the one it realises, because a thing cannot be built before it is found or checked before it is built. The same rule makes a document orderable as a directed acyclic graph: a genesis inversion and a forward reference are one defect seen from two sides.",
                },
                { code: GRANULARITY_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "three granularities" },
                { code: FLOW_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "contracts in order" },
                { code: GENESIS_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "verb to stage" },
                { caption: "split or combine", kind: "mermaid", text: BOUNDARY_DIAGRAM },
                { caption: "forward flow", kind: "mermaid", text: FLOW_DIAGRAM },
            ],
            title: "Boundaries, data flow, genesis",
        },
    ],
    title: "Node design",
};