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

const OPERATION_SAMPLE =
    '# SEMANTIC OPERATION BOUNDARY · a node states WHAT as an operation; an adapter decides HOW\n\n# discover, read, search, analyze · operations against a tree that produce values\nDISCOVER_RESOURCES "<pattern>" INTO <resources>\nREAD_RESOURCE <resource> INTO <content>\nSEARCH_CONTENT <content> FOR <term> INTO <matches>\nANALYZE_CONTENT <content> AGAINST <criteria> INTO <findings>\nEXTRACT_FACTS <fields> FROM <content> INTO <facts>\nCALCULATE_METRIC <measure> FROM <facts> INTO <value>\n\n# compose, validate, persist · operations that leave an artifact\nCOMPOSE_ARTIFACT <artifact> FROM <facts> USING <shape>\nVALIDATE_ARTIFACT <artifact> AGAINST <schema>\nPERSIST_ARTIFACT <artifact> TO <destination>\n\n# execute, decide, report · effects outside the tree and on other parties\nEXECUTE_TOOL <command> WITH timeout: <bound> INTO <result>\nREQUEST_DECISION <party> WITH options: [<a>, <b>] INTO <choice>\nREPORT_RESULT <artifact> TO <the parties whose next work it creates>';

const BINDING_SAMPLE =
    "# the document names an operation and a slot · one adapter per harness resolves both, outside the document\nREAD_RESOURCE {project.governance_policy} INTO <policy>\nEXECUTE_TOOL {toolchain.verify_command} INTO <verdict>\n\nadapter:\n    DISCOVER_RESOURCES -> <the harness's discovery tool>\n    READ_RESOURCE      -> <the harness's read tool>\n    SEARCH_CONTENT     -> <the harness's search tool>\n    EXECUTE_TOOL       -> <the harness's shell>\n    PERSIST_ARTIFACT   -> <the harness's write tool>\n    REQUEST_DECISION   -> <the harness's question surface, or ABSENT for a bounded reader>\n    {project.governance_policy} -> <the path in this tree>\n    {toolchain.verify_command}  -> <the command in this tree, or ABSENT>";

const FORMS_SAMPLE =
    'READ_RESOURCE <resource>                                 # the operation and its target\nREAD_RESOURCE <resource> INTO <parsed>                   # bound to a name the next line reads\nSEARCH_CONTENT <scope> FOR <term> WITH glob: "*.md"      # named parameters\nEXECUTE_TOOL <command> -> <result>                       # the arrow is the same binding';

const BINDING_DIAGRAM =
    'flowchart TB\n    doc["The document · semantic operations and {slots}"]\n    adapter["One adapter per harness"]\n    harnessA["Harness A · its read tool, its shell, its question surface"]\n    harnessB["Harness B · different tools, same document"]\n    absent["A slot with no analogue · declared ABSENT, the branch does not run"]\n    doc --> adapter\n    adapter --> harnessA\n    adapter --> harnessB\n    adapter -. no analogue .-> absent';

const EFFECT_DIAGRAM =
    'flowchart LR\n    op["Operation · what happens"]\n    target["Target · what it acts on"]\n    params["WITH · named parameters"]\n    result["INTO or arrow · where the result lands"]\n    addressable["An effect the adapter can perform and the next line can read"]\n    op --> target --> params --> result --> addressable';

export const INVOCATION_SECTION: Section = {
    icon: INVOCATION_SECTION_ICON,
    id: INVOCATION_SECTION_ID,
    intro: "Every external effect in a document is a named semantic operation with explicit parameters and an explicit result binding, the parts <cite>invocation parts</cite> names and <cite>invocation forms</cite> writes four ways. The operation says what happens, and <cite>the operations</cite> groups them by the kind of effect. An adapter, one per harness and outside the document, decides how, the split <cite>document and adapter</cite> shows and <cite>one adapter per harness</cite> draws. An invocation is the act stage of the loop and yields a procedure.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Name every effect with a semantic operation, give it a target, pass parameters through a named clause and bind the result to a name the next line can read. Refer to a location or a command through a slot the adapter resolves, never a literal path. Keep the harness's own tool names, configuration files and features out of the document.",
                    boundary:
                        "A document written for exactly one throwaway session may name whatever it likes, because nothing will port it. The discipline is for a document that will be walked again, by another party, or under another harness.",
                    cause: "A tool name is a fact about one harness, and a document that carries it is bound to that harness by the first line that does.",
                    decision:
                        "Split the document from the harness at the operation, one adapter per harness, rather than one document per harness.",
                    failureMode:
                        "A library of documents names one harness's tools throughout, the harness changes its tool set, and every document breaks at once. That is vendor lock-in leakage, with nothing in any document explaining why.",
                    kind: "lesson",
                    principle:
                        "A document names semantic operations, and one adapter resolves them to tools by late binding.",
                    problem:
                        "An effect described in prose is not addressable by any adapter, and an effect named by one harness's tool is hardcoded configuration addressable by only that harness.",
                    validation:
                        "Rename the harness under the document and hand it to a different model. Where a line fails, it carried a tool name or a path where an operation or a slot belonged, and the adapter is where the fix lands.",
                },
                {
                    kind: "text",
                    text: "The operations partition by the kind of effect: those that act on a tree and produce values, those that leave an artifact in it, and those that reach outside it or address another party. Each carries a semantic contract, so a document relies on the contract rather than on what a particular tool happens to do.",
                },
                {
                    kind: "text",
                    text: "Portability follows from the boundary. Operations and slots in the document are configuration externalization applied to an instruction; one adapter per harness is the adapter pattern. A slot with no analogue resolves as absent, as limits states, and a decision request is the clearest case: a participant has a question surface and a bounded reader does not, so the same operation resolves for one and is absent for the other, and the document is unchanged. The model a document walks under is a slot by construction, because model selection belongs to the harness.",
                },
                { code: OPERATION_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "the operations" },
                { code: BINDING_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "document and adapter" },
                { code: FORMS_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "invocation forms" },
                { caption: "one adapter per harness", kind: "mermaid", text: BINDING_DIAGRAM },
                { caption: "invocation parts", kind: "mermaid", text: EFFECT_DIAGRAM },
            ],
            title: "Operations, not tools",
        },
    ],
    title: "Semantic operations",
};