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

const ABSENCE_SAMPLE =
    '# what a document cannot do · declared where a reader would otherwise assume it\nLIMIT <execution>:      "a document has no runtime · a reasoning loop walks it and an adapter performs its effects"\nLIMIT <determinism>:    "the same document may produce different results across runs"\nLIMIT <introspection>:  "a gate checks an outcome · never the model\'s confidence"\nLIMIT <portability>:    "a document written for one model behaves differently under another"\nLIMIT <persistence>:    "nothing survives a session unless a directive writes it"\nLIMIT <concurrency>:    "a parallel group declares independence · the harness decides what runs together"\nLIMIT <availability>:   "an operation assumes the adapter resolves it · an absent resolution is declared, never assumed"\nLIMIT <feedback>:       "a document describes a linear or branching flow · watching for change needs a tool"';

const SLOT_SAMPLE =
    '# a slot resolves to one of three states, and the third is the load-bearing one\nSLOT {toolchain.watch}:    ABSENT    "this harness cannot block on a surface · the branch does not run"\nSLOT {toolchain.parallel}: RESOLVED  "the harness runs a parallel group together"\nSLOT {project.checkpoint}: DEFERRED  "a reversible checkpoint will exist · the branch is blocked, not skipped"\n\nWHEN <a directive names a slot>:\n    IF <slot> is ABSENT:   DECLARE the absence · SKIP the branch\n    IF <slot> is DEFERRED: DECLARE the deferral · BLOCK the branch\n    IF <slot> is RESOLVED: RUN the branch';

const CONTEXT_SAMPLE =
    "# a bounded context is a limit, not a surprise\nWHEN <document> exceeds <what one reading consumes>:\n    SPLIT <document> INTO <nodes the reader takes one at a time>\n    CARRY <the output the next node's contract reads> · never the whole history\n\nWHEN <a workflow runs longer than one session>:\n    PERSIST_ARTIFACT <what the next session reads> TO <a surface>\n    READ_RESOURCE <it> at the start of the next · the document itself remembers nothing";

const LIMIT_DIAGRAM =
    'flowchart TB\n    doc["A document"]\n    reaches["Reaches · the input the loop reads"]\n    not["Does not reach"]\n    exec["Execution · the binding performs the effects"]\n    out["Output · a sample, every run"]\n    inner["The model\'s confidence"]\n    other["Another model\'s behaviour"]\n    doc --> reaches\n    doc -. never .-> not\n    not --> exec\n    not --> out\n    not --> inner\n    not --> other';

const SLOT_DIAGRAM =
    'flowchart LR\n    slot["A slot a directive names"]\n    adapter{"What does the adapter say?"}\n    resolved["RESOLVED · the branch runs"]\n    absent["ABSENT · declared, the branch does not run"]\n    deferred["DEFERRED · declared, the branch is blocked"]\n    faked["Nothing declared · the branch runs against a guess"]\n    slot --> adapter\n    adapter -- a value --> resolved\n    adapter -- absent --> absent\n    adapter -- deferred --> deferred\n    adapter -. no declaration .-> faked';

export const LIMITATION_SECTION: Section = {
    icon: LIMITATION_SECTION_ICON,
    id: LIMITATION_SECTION_ID,
    intro: "A document's limits are stated where a reader would otherwise assume the opposite, as <cite>declared limits</cite> writes and <cite>what it never reaches</cite> draws, and each is a limit to design for rather than a flaw to route around. A slot resolves to one of the three states <cite>slot states</cite> names and <cite>three states</cite> draws, and a reading larger than one session is split as <cite>size and time</cite> shows.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Declare each limit beside the mechanism a reader would otherwise expect to cover it. Split a document that exceeds one reading into nodes the reader takes one at a time, and carry across sessions only what a directive persists to a surface.",
                    boundary:
                        "A limit declared is not a limit removed. Stating that output is probabilistic is what makes the gates necessary, and a reader who treats the declaration as a disclaimer has read the page backwards.",
                    cause: "A branch runs against a value unless something says there is none, so a missing declaration reads as a value.",
                    decision:
                        "Refuse an adapter that resolves everything, and route each branch by the slot's declared state rather than by whether a value happens to exist.",
                    failureMode:
                        "A workflow declares a parallel group and a watch on a surface, the harness has neither, both branches run against a guess, and the workflow reports every gate green over work that never happened.",
                    kind: "lesson",
                    principle:
                        "An absence is declared where it would otherwise be assumed, and a slot with no analogue is absent rather than faked.",
                    problem: "A directive names a capability the harness may not have.",
                    validation:
                        "For each slot a document names, find its state in the adapter. A slot with no state is a branch running against a guess, and the fix is a declaration rather than a value.",
                },
                {
                    kind: "text",
                    text: "The limits partition by what a document can and cannot reach. It reaches the input a reasoning loop reads, and nothing past that. Output is a sample from a distribution every run, so reproducibility is not on offer, and the model's confidence is not observable from outside, so a gate cannot condition on it. A document that names its model has written a claim into a slot the harness owns.",
                },
                {
                    kind: "text",
                    text: "The third slot state is what keeps a document honest. An adapter is a capability declaration, and one that resolves everything is lying about something. Size and time are facts about the party reading the document: a context is bounded, so what crosses a node boundary is the output the next contract reads rather than the whole history, and a session ends, so what the next one needs is persisted rather than remembered.",
                },
                { code: ABSENCE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "declared limits" },
                { code: SLOT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "slot states" },
                { code: CONTEXT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "size and time" },
                { caption: "what it never reaches", kind: "mermaid", text: LIMIT_DIAGRAM },
                { caption: "three states", kind: "mermaid", text: SLOT_DIAGRAM },
            ],
            title: "Declared, never assumed",
        },
    ],
    title: "Limits",
};