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

const ITEM_SAMPLE =
    "# an item is a typed span · its kind selects how it closes, and the closure is checked by someone other than its author\nDECLARE item: object\nSET item = {\n  id:    <allocated by the surface, never by hand>,\n  kind:  <artifact | judgement>,\n  from:  <this party>,\n  to:    [<the parties that need it>],\n  body:  {surface: <where>, locus: <what part>, observed: <what was seen>, expected: <what should hold>}\n}\n\nFUNCTION closes(item):\n  # an artifact item asks for something that can exist · it closes when a typed reference resolves\n  IF item.kind == artifact: RETURN resolves(item.satisfied_by) AND monotone_with_the_work(item.satisfied_by)\n  # a judgement item asks for a reading · it closes by its declared acknowledger, with nothing to point at\n  IF item.kind == judgement: RETURN acknowledged_by(item.acknowledger)\n\nFUNCTION may_close(party, item):\n  RETURN party IN item.to   # a reader, never the author";

const SIGNAL_SAMPLE =
    '# a failure is a finding, not a halt · it flows through the same channel and routes by what it binds\nFUNCTION route(failure):\n  SET finding = {surface: failure.surface, locus: failure.locus, observed: failure.observed, expected: failure.expected}\n  IF failure.blocks_a_decision:\n    RETURN SEND finding TO <the party whose surface the decision binds>\n  IF failure.asks_what_the_work_is_for:\n    RETURN SEND finding TO <the person> AS <a question with a recommendation first>\n  RETURN <the next open item>\n\n# NODE 9 — COMMIT   [evaluative · representation · information-theory · yields: one typed artifact]\nCONTRACT:\n  input:        findings + run_context\n  transform:    emit exactly one artifact of the kind bound at orientation, deduplicated, naming every limitation\n  constraints:  a report goes to the parties whose next work it creates, never to the person as a closing summary\n  output:       committed { artifact_type, output }\n  handoff:      one typed artifact emitted (yields: hash + boolean)\n\nHANDOFF GATE (evidence-bearing):\n  rule_id: "COMMIT"   yields: hash + boolean\n  [check] exactly one artifact emitted, of the kind bound at orientation (evidence: committed.artifact_type)\n  [check] every finding addressed to a party that needs it (evidence: findings[].to) over: findings measured: <addressed> / <findings>\n  [check] no finding recorded twice (evidence: dedup)\n  refuse: the artifact\'s destination changed since it was read before PERSIST_ARTIFACT\n  result: pass -> NODE 10 | duplicate or unaddressed -> REPAIR (owner: NODE 9) | unknown -> BLOCKED';

const CLOSE_SAMPLE =
    "# closing an item · the handler removes it, never the author, and extraction comes first\nWHEN <party> handles <item>:\n    VALIDATE <party> IN <item>.<to>\n    VALIDATE closes(<item>)\n    EXTRACT_FACTS <item>.<durable half> INTO <the one home history has>\n    PERSIST_ARTIFACT <the extraction> TO <that home>\n    REMOVE <item> BY <item>.<id>       # the span, never a matched line";

const ITEM_DIAGRAM =
    'flowchart TB\n    posted["An item is posted · id allocated, kind set, readers named"]\n    kind{"Which kind?"}\n    artifact["Artifact · closes when its reference resolves"]\n    judgement["Judgement · closes when its acknowledger marks it"]\n    handler["Removed by a party in its reader set · never its author"]\n    extract["Its durable half extracted first"]\n    posted --> kind\n    kind -- artifact --> artifact --> handler\n    kind -- judgement --> judgement --> handler\n    handler --> extract';

const FAILURE_DIAGRAM =
    'flowchart LR\n    fails["A gate fails"]\n    finding["A finding · surface, locus, observed, expected"]\n    binds{"What does it bind?"}\n    owner["The party whose surface the decision binds"]\n    person["The person · what the work is for, a recommendation first"]\n    next["The next open item"]\n    fails --> finding --> binds\n    binds -- a decision --> owner\n    binds -- the purpose --> person\n    binds -- nothing --> next';

export const HANDOFF_SECTION: Section = {
    icon: HANDOFF_SECTION_ICON,
    id: HANDOFF_SECTION_ID,
    intro: "A handoff is an item addressed to the parties that need it, with an allocated id, a declared kind and a closure the kind selects, as <cite>an item</cite> writes and <cite>kind selects closure</cite> draws. An artifact item asks for something that can exist and closes when a typed reference to it resolves. A judgement item asks for a reading and closes when its acknowledger marks it; <cite>closing an item</cite> is the closure either way. A failure is a finding rather than a halt, the route <cite>failure routes</cite> and <cite>failure to finding</cite> follow, and a report goes to the parties whose next work it creates, never to the person as a closing summary.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Post a handoff as an item with an id the surface allocates, a kind, the parties it is addressed to and a body carrying the finding's surface, locus, observed and expected values. Let an artifact item close by a reference that must resolve and stay true while the work is done, and a judgement item close by its acknowledger. Route a failure by what it binds: a decision to the party whose surface it binds, a question of purpose to the person with a recommendation first, and everything else to the next open item.",
                    boundary:
                        "The handoff protocol is for parties that share a surface; what a bounded reader does instead is composing a collaboration's.",
                    cause: "A closure that a reference decides can be checked by anyone; a closure that a party declares can be checked by nobody but that party.",
                    decision:
                        "Let the kind decide the closure, a reference that must resolve or an acknowledger named on the item, rather than the author's word that it is done.",
                    failureMode:
                        "A party declares an item handled, nothing points at the thing it asked for, the item is removed, and the work it named was never done.",
                    kind: "lesson",
                    principle:
                        "A handoff is a typed item whose closure is falsifiable by someone other than its author.",
                    problem: "A handoff closed by whoever wrote it closes whether or not the work exists.",
                    validation:
                        "For each closed item, name the reference that closed it or the party that acknowledged it. An item closed by its own author with no reference was declared done, not shown done.",
                },
                {
                    kind: "text",
                    text: "The kind is on the item and it selects the closure. An artifact item names something that can exist, a file, a gate, a record, so it closes with a typed reference that must resolve. The reference names a condition that can be wrong rather than a path, because a path resolves the moment the file exists and the item reads closed while the defect is open. The reference is also monotone with the work: true when the work is done and false when it is not, so a citation pointing at the findings themselves is refused, since a broken tree would satisfy it. A judgement item closes by its declared acknowledger with no reference; why the acknowledger is required by one kind and forbidden by the other is the board and the venue's.",
                },
                {
                    kind: "text",
                    text: "A failure flows through the same channel as any other item and routes by what it binds: a decision to the party whose surface it binds, a question of purpose to the person, everything else to the next open item, the routes a turn never ends to wait derives. A gate's result line is the same routing in miniature, with a third arm the item channel also needs: an unknown, a claim the run could not measure, is blocked rather than passed, and blocked is a state that names the party who owes the answer. The commit node carries the rule that a report goes to the parties whose next work it creates.",
                },
                {
                    kind: "text",
                    text: "The handler removes the item by its id, after extraction, as the board and the venue requires; an item whose readers are all gone is re-addressed rather than left, since an item nobody can handle reads as live traffic forever.",
                },
                { code: ITEM_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "an item" },
                { code: SIGNAL_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "failure routes" },
                { code: CLOSE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "closing an item" },
                { caption: "kind selects closure", kind: "mermaid", text: ITEM_DIAGRAM },
                { caption: "failure to finding", kind: "mermaid", text: FAILURE_DIAGRAM },
            ],
            title: "Typed items, falsifiable closures",
        },
    ],
    title: "Handoff signals",
};