import { ARCHITECTURE_ICON, METHODOLOGY_ICON } from "#configuration/icons/page.icons";
import { ARCHITECTURE_PAGE, METHODOLOGY_PAGE } from "#core/ids/page.ids";
import { ARCHITECTURE_TITLE, METHODOLOGY_TITLE } from "#configuration/strings/page.strings";
import type { LinkEntry } from "#types/block.types";
import { METHOD_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { METHOD_SECTION_ID } from "#core/ids/grammar.ids";
import type { Section } from "#types/document.types";
import { pagePath } from "#assets/link.assets";

const METHOD_LINKS: readonly LinkEntry[] = [
    {
        description:
            "The loop, who does what, the stance, the gates and the coordination the grammar is written inside.",
        href: pagePath(METHODOLOGY_PAGE),
        icon: METHODOLOGY_ICON,
        text: METHODOLOGY_TITLE,
    },
    {
        description: "The principle canon, the tensions and the decay paths a document's constraints are drawn from.",
        href: pagePath(ARCHITECTURE_PAGE),
        icon: ARCHITECTURE_ICON,
        text: ARCHITECTURE_TITLE,
    },
];

const INSTRUMENT_DIAGRAM =
    'flowchart TB\n    subgraph method["The method · holds the work"]\n        worth["Worth before work"]\n        gates["Checks that hold the rules"]\n        evidence["Evidence, never a claim"]\n        seats["Coordination between parties"]\n    end\n    subgraph grammar["The grammar · shapes one input"]\n        doc["A document · typed, contracted, gated, bounded"]\n    end\n    worth --> doc\n    doc --> gates\n    gates --> evidence\n    seats -. every party reads the same document .-> doc';

const ADDS_DIAGRAM =
    'flowchart LR\n    subgraph adds["What the grammar adds"]\n        tokens["Tokens the model weights"]\n        order["A processing order"]\n        exits["Explicit exit criteria"]\n        bounds["Boundaries the model can quote"]\n    end\n    narrow["A narrower completion set · never a promise about the completion"]\n    tokens --> narrow\n    order --> narrow\n    exits --> narrow\n    bounds --> narrow';

export const METHOD_SECTION: Section = {
    icon: METHOD_SECTION_ICON,
    id: METHOD_SECTION_ID,
    intro: "A document is one instrument, one input inside the loop the method owns, as <cite>one input</cite> draws. It shapes what a model reads, and nothing about it decides whether the work was worth doing, whether the result is true, or how several parties share one tree; worth before work, it looked right and coordination is software on the methodology page hold those. Where a section here touches them, it shows how a document expresses them and leaves the reasoning where it lives.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Use a document to shape one input: the instruction a party reads before it acts. Hold everything around that input with the method: decide worth before the document is written, check the output with a gate the document did not run, and coordinate parties through surfaces the document only reads.",
                    boundary:
                        "A collaboration with no tools and no shared tree is a conversation, and a document there is a well-shaped message. The instrument does its work where an adapter can perform what the document names.",
                    cause: "A well-shaped input reads as a guarantee because the output usually matches it, and the failures live in the runs where it does not.",
                    decision:
                        "Put the checks outside the document, in a gate the method runs, rather than inside it as sentences the model completes.",
                    failureMode:
                        "A team writes careful documents, skips the checks because the documents read as complete, and discovers in production that a gate the model reported as passed was never evaluated by anything.",
                    kind: "lesson",
                    principle: "The grammar shapes an input, and the method holds the work around it.",
                    problem:
                        "A document that reads well invites the belief that it did what it says, and a document cannot verify itself.",
                    validation:
                        "Take a document that reported every gate passed and run the checks the method names over its output. A gate the checks contradict was a sentence the model completed, and the document could not have known.",
                },
                {
                    kind: "text",
                    text: "What a document adds to a collaboration is concrete, <cite>what it adds</cite> lists it, and each addition narrows the completion set without promising what the model will do with it. What it cannot add is stated under limits, and it looked right, verify the verifier and a report, not a checkbox exist because those absences are real.",
                },
                { kind: "link", links: METHOD_LINKS },
                { caption: "one input", kind: "mermaid", text: INSTRUMENT_DIAGRAM },
                { caption: "what it adds", kind: "mermaid", text: ADDS_DIAGRAM },
            ],
            title: "One instrument inside a method",
        },
    ],
    title: "PAG and the method",
};