import { INTEGRATION_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { INTEGRATION_SECTION_ID } from "#core/ids/grammar.ids";
import { PAG_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";
import { templateBodyOf } from "#core/converters/grammar.converter";

const INSTANTIATE_SAMPLE =
    '# instantiation · from a request to a gated node chain\n\n# STEP 1: the transition · what state of the tree the request asks for\n    Request:    "route each incoming request to the handler that owns it"\n    Transition: <a registry that resolves a handler by a request\'s type>\n\n# STEP 2: the protocol · by semantic fit against each use-when, with the reason\n    Chosen:     <resolve-through-a-registry>\n    Reason:     "keyed resolution is justified · handlers vary, the key does not"\n    Chain:      ANALYZE -> FIND -> CREATE -> LINK -> VERIFY\n\n# STEP 3: the nouns · the task\'s own, so no placeholder survives\n    <candidates> = the handlers declared in {project.handler_registry}\n    <key>        = <request>.<type>\n\n# STEP 4: the nodes · one per verb, tagged with its stage, each contract reading the prior output\n# NODE 1 — ANALYZE THE REQUESTS   [epistemic · analysis · logic · yields: set]\n@genesis: difference\nCONTRACT:\n  input:     <queue>\n  transform: READ_RESOURCE <queue> INTO <incoming>; EXTRACT_FACTS <type> FROM <incoming> INTO <keys>\n  output:    <keys>, one per request\nHANDOFF GATE:\n  [check] <incoming> read from <queue> (evidence: the read returned requests)\n  [check] a <key> resolved for every <request> (evidence: the two counts match) over: <incoming> measured: <keyed> / <requests>\n  [check] no <request> carries an unknown <type> (evidence: every key in the declared set)\n  result: pass -> NODE 2 | unknown type -> REPAIR (owner: NODE 1) | unknown -> BLOCKED\n\n# NODE 2 — FIND THE HANDLER       [epistemic · ontology · set-theory · yields: set]\n@genesis: existence\nCONTRACT:\n  input:     <keys> from NODE 1\n  transform: FOR EACH <key> IN <keys>: FIND <handler> IN <candidates> WHERE <handler>.<owns> == <key> INTO <matched>\n  output:    <matched>\nHANDOFF GATE:\n  [check] exactly one <handler> per <request> (evidence: the two counts match, no duplicates) over: <keys> measured: <matched> / <keys>\n  [check] every <handler> in <matched> is declared in {project.handler_registry} (evidence: a lookup per handler)\n  [check] an unmatched <request> reported, never dropped (evidence: the report names each)\n  result: pass -> NODE 3 | duplicate handler -> REPAIR (owner: NODE 2) | unknown -> BLOCKED\n\n# NODE 3 — CREATE THE ROUTE       [epistemic · formalisation · computation · yields: procedure]\n@genesis: structure\nCONTRACT:\n  input:     <matched> from NODE 2\n  transform: COMPOSE_ARTIFACT <route> FROM <matched> USING <the route shape here>\n  output:    <route>\nHANDOFF GATE:\n  [check] <route> names its <handler> and its <key> (evidence: both fields non-empty)\n  [check] one <route> per <matched> entry (evidence: the two counts match) over: <matched> measured: <routed> / <entries>\n  [check] <route> conforms to <the route shape here> (evidence: VALIDATE_ARTIFACT passed)\n  result: pass -> NODE 4 | nonconforming -> REPAIR (owner: NODE 3) | unknown -> BLOCKED\n\n# NODE 4 — LINK THE ROUTE         [epistemic · reasoning · graph · yields: edge-list]\n@genesis: relation\nCONTRACT:\n  input:     <route> from NODE 3\n  transform: LINK <route> TO <the dispatch table>\n  output:    the dispatch entry\nHANDOFF GATE:\n  [check] <route> resolves from <the dispatch table> (evidence: a lookup returns it)\n  [check] no earlier <route> for <key> remains (evidence: one entry per key) over: dispatch entries measured: <one per key> / <keys>\n  [check] nothing else in <the dispatch table> changed (evidence: a diff of the entries)\n  result: pass -> NODE 5 | stale entry -> REPAIR (owner: NODE 4) | unknown -> BLOCKED\n\n# NODE 5 — VERIFY THE DISPATCH    [evaluative · verification · logic · yields: boolean]\n@genesis: constraint\nCONTRACT:\n  input:     the dispatch entry from NODE 4\n  transform: EXECUTE_TOOL <route> WITH <request> INTO <response>; PERSIST_ARTIFACT <response> TO <outbox>; EXECUTE_TOOL {toolchain.verify_command} INTO <verdict>; VALIDATE_ARTIFACT <verdict> AGAINST <green on one full run>\n  output:    <verdict>\nHANDOFF GATE:\n  [check] <response> persisted (evidence: a read of <outbox> returns it)\n  [check] <response>.<handled-by> equals <matched>.<handler> (evidence: the two values) over: <requests> measured: <handled by the matched handler> / <requests>\n  [check] <verdict> green on one full run (evidence: the run\'s own output)\n  refuse: <outbox> changed since it was read before PERSIST_ARTIFACT\n  standing: moved-set <the files changed since NODE 4>\n  result: pass -> TERMINATE | wrong handler -> REPAIR (owner: NODE 2) | unknown -> BLOCKED';

const DISTILL_SAMPLE = templateBodyOf("DISTILLATION");

const BOUNDARY_SAMPLE =
    "# the boundary principles · a base is justified only when every one holds, with the evidence that shows it\nuniversal       every instance in the family is an instance of the shared behaviour\ninvariant       the shared half does not vary across them\nfoundational    other behaviour composes from it\nenforceable     a check can hold it\nload-reducing   it removes work rather than adding a layer\n\n# otherwise the verdict is compose, a utility, or a local refactor · never a base";

const INSTANTIATE_DIAGRAM =
    'flowchart LR\n    request["A request"]\n    transition["The transition it asks for"]\n    protocol["The protocol that fits, with its reason"]\n    nouns["Placeholders bound to the task\'s nouns"]\n    nodes["Nodes · tagged, contracted, gated"]\n    request --> transition --> protocol --> nouns --> nodes';

const DISTILL_DIAGRAM =
    'flowchart TB\n    measure["Measure what exists"]\n    worth["Rank candidates by worth"]\n    sign["Sign each class from behaviour"]\n    boundary{"Universal, invariant, foundational, enforceable, load-reducing?"}\n    base["Compose the base · migrate reversibly"]\n    gone{"Old pattern gone from the whole scope?"}\n    registry["Regenerate the registry · measure the reduction"]\n    other["Compose, a utility, or a local refactor"]\n    measure --> worth --> sign --> boundary\n    boundary -- all five --> base --> gone\n    boundary -- any fails --> other\n    gone -- no --> base\n    gone -- yes --> registry';

export const INTEGRATION_SECTION: Section = {
    icon: INTEGRATION_SECTION_ICON,
    id: INTEGRATION_SECTION_ID,
    intro: "Two movements connect protocols to work. Instantiation takes a request to a node chain, in the order <cite>instantiation order</cite> draws and <cite>instantiation</cite> writes: name the transition the request asks for, choose the protocol by fit, bind its placeholders to the task's nouns, and expand its chain into tagged nodes, each with a contract and a gate. Distillation takes repeated behaviour to one shared base, and it is a document type of its own: an epistemology walked on the reasoning axis, gated on evidence that the base is universal, invariant, foundational, enforceable and load-reducing, the five <cite>boundary principles</cite> names. It is incomplete until the old pattern is proven gone, as <cite>distillation order</cite> draws. <cite>distillation</cite> is the grammar's own template record.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Instantiate by naming the transition first, choosing the protocol whose use-when fits it and recording the reason, binding each placeholder to a noun the task owns, and expanding the chain into nodes whose contracts read the prior output and whose gates carry three to five checks with evidence. Distil only after measuring what exists and ranking the candidates by worth. Sign every class from its behaviour, prove the five boundary principles with the evidence that shows each, compose the base within its size limit, migrate each target reversibly from the simplest up, and scan the whole scope for the old pattern before declaring anything complete.",
                    boundary:
                        "A base is justified by behaviour, never by names that look alike; when a shape earns a template is core templates'.",
                    cause: "A base is a promise that every future instance shares one behaviour, and a promise made from one instance or from a naming resemblance has nothing to be checked against.",
                    decision:
                        "Sign the classes from their behaviour and let the five principles decide, rather than raise a base from what the names have in common.",
                    failureMode:
                        "A base is raised from two classes whose names rhyme, three later classes are forced to extend it, and each one overrides most of what it inherited because the shared half was the name.",
                    kind: "lesson",
                    principle:
                        "A protocol is instantiated by transition and a base is distilled by behavioural evidence, never copied from one case or a resemblance.",
                    problem:
                        "A base promoted from one instance or a resemblance is that instance's accidents wearing a template's clothes.",
                    validation:
                        "For a base, name the second instance that justified it, the behavioural signature each class was signed with, and the evidence behind each of the five principles. A base with one instance, a name-based signature or an unproven principle is a template that will fight its next user.",
                },
                {
                    kind: "text",
                    text: "Instantiation names the transition first, because from intent to structure selects the protocol by it, and it ends when no placeholder survives.",
                },
                {
                    kind: "text",
                    text: "Distillation measures before it proposes, because a missing adoption of an existing base looks like a missing abstraction until the registry is read. It signs every class from behaviour rather than names: initialisation, lifecycle, error handling, state, dependencies. The base is concrete responsibilities plus abstract hooks, a template method pattern, and a single stray occurrence outside the approved locations is a refutation whose result line routes back to composition. The last gate measures the reduction rather than asserting it, so the single source of truth for what bases exist is the registry and never the memory of the party that distilled.",
                },
                { code: INSTANTIATE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "instantiation" },
                { code: DISTILL_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "distillation" },
                { code: BOUNDARY_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "boundary principles" },
                { caption: "instantiation order", kind: "mermaid", text: INSTANTIATE_DIAGRAM },
                { caption: "distillation order", kind: "mermaid", text: DISTILL_DIAGRAM },
            ],
            title: "Instantiate and distil",
        },
    ],
    title: "Integrating algorithms",
};