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

const DAG_SAMPLE =
    '# NODE 5 — PROJECT   [epistemic · reasoning · graph · yields: edge-list]\n@purpose: "Declare the order as edges, so a reader who did not write it can still resolve it"\n@cue: "DECLARE_THE_EDGES"\n\nCONTRACT:\n  input:        <the units of work>\n  transform:    for each unit -> name what it depends on -> refuse a cycle -> name the groups that are independent\n  constraints:  a successor is declared by name, never derived from a position; at most one unit that holds the others is open at a time\n  output:       DAG <units>\n  handoff:      acyclic AND every unit names its dependencies (yields: edge-list + boolean)\n\nDAG <units>:\n    NODE <unit-a>:\n        <what settles it>\n    NODE <unit-b> AFTER <unit-a>:\n        <what settles it>\n    NODE <unit-c> DEPENDS_ON [<unit-a>]:\n        <what settles it>\n    PARALLEL_GROUP: <unit-b>, <unit-c>\n\nHANDOFF GATE (evidence-bearing):\n  rule_id: "PROJECT"   yields: edge-list + boolean\n  [check] no unit depends on itself through any path (evidence: the walk over DAG <units>) over: <units> measured: <acyclic> / <units>\n  [check] every successor is named, none is a number (evidence: the AFTER and DEPENDS_ON clauses)\n  [check] at most one holding unit is open (evidence: count of open holds)\n  result: pass -> NODE 6 | a cycle -> REPAIR (owner: NODE 5) | unknown -> BLOCKED';

const MACHINE_SAMPLE =
    "# a lifecycle as a closed set of states · a transition names its trigger and its guard\nSTATE_MACHINE <unit>:\n    STATE <planned>:\n        ENTRY: <no artifact exists yet>\n    STATE <open>:\n        ENTRY: <a party has begun>\n    STATE <settled>:\n        ENTRY: <every condition of the exit holds>\n    STATE <retired>:\n        ENTRY: <what the settlement implies has landed>\n\n    TRANSITION FROM <planned> TO <open> ON <first-reading>\n    TRANSITION FROM <open> TO <settled> ON <exit-condition>\n        GUARD: <every party that must agree has agreed>\n    TRANSITION FROM <settled> TO <retired> ON <implied-work-landed>\n        GUARD: <nothing the settlement distributed is still open>\n    TRANSITION FROM <open> TO <planned> ON <artifact-removed>\n        GUARD: <no argument has landed yet>\n\nFUNCTION state_of(unit):\n  # derived from the tree on every read · never written by a party\n  IF NOT EXISTS(unit.artifact): RETURN <planned>\n  IF every_exit_condition_holds(unit) AND implied_work_landed(unit): RETURN <retired>\n  IF every_exit_condition_holds(unit): RETURN <settled>\n  RETURN <open>";

const PARALLEL_SAMPLE =
    '# NODE 6 — ACT   [epistemic · formalisation · computation · yields: procedures]\nCONTRACT:\n  input:        DAG <units>\n  transform:    run each independent group as bounded readers -> join their artifacts -> a participant waits rather than returns\n  constraints:  a bounded reader receives a task and nothing shared; whether a group runs together is the harness\'s fact, declared independence is the document\'s\n  output:       artifacts[] per group\n  handoff:      every group joined or explicitly still open (yields: procedure)\n\nPARALLEL:\n    TASK "<investigate unit b · mutate nothing>" WITH agent: <role-b> -> <artifact-b>\n    TASK "<investigate unit c · mutate nothing>" WITH agent: <role-c> -> <artifact-c>\nEND\nAWAIT <artifact-b>, <artifact-c> INTO <artifacts>\n\n# a participant does not join · it waits, and a wait is a call rather than a halt\nWAIT ON <the shared surface> AS <party> INTO <change>\nIF <change> == <changed>:\n    READ_RESOURCE <the shared surface> whole INTO <current>';

const DECLARED_DIAGRAM =
    'flowchart TB\n    prose["Prose · \'first do this, then that, meanwhile the other\'"]\n    implied["Ordering implied by sentence order · the model reconstructs it"]\n    declared["A construct · DAG, STATE_MACHINE, PARALLEL, AWAIT, WAIT"]\n    explicit["Edges, states and groups every reader shares"]\n    prose --> implied\n    declared --> explicit';

const ORDINAL_DIAGRAM =
    'flowchart LR\n    ordinal["An ordinal · a position in a total order"]\n    hidden["A unit raised before its predecessor settles · every number still intact"]\n    name["A declared successor · an edge in a partial order"]\n    caught["A successor nobody created, or a unit no predecessor declared · both decidable"]\n    ordinal -. preserves the violation .-> hidden\n    name --> caught';

export const ORCHESTRATION_SECTION: Section = {
    icon: ORCHESTRATION_SECTION_ICON,
    id: ORCHESTRATION_SECTION_ID,
    intro: "Orchestration is the part of a document that says how work is ordered and where it runs in parallel, and the grammar refuses to let that be implied. A document declares the structure with constructs, each grounded to the representation it makes explicit, the split <cite>prose or construct</cite> draws. There is a dependency graph for a partial order with forward dependencies, which <cite>dependency graph</cite> declares by name because <cite>name, never number</cite> is what a name buys, and a finite state machine for a lifecycle drawn from a closed set of states, as <cite>state machine</cite> shows. Beside them a priority queue for a ranking, a flowchart for the rendered projection of any of them, a surface for state several parties share, a parallel block for readers that return, and a wait for a reader that never does, the pair <cite>join and wait</cite> writes. The method teaches the same as the plan is a graph; here it is the project stage of the loop, and it yields an edge-list. Ordering carried by sentence order is temporal coupling, and a model given prose reconstructs a structure of its own.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Model an order as a dependency graph whose nodes name what they depend on, so the order is partial and a number never stands in for an edge. Model a lifecycle as a finite state machine whose states are a closed set, whose transitions name their trigger and their guard, and whose current state is derived from the tree by a function rather than written by a party. Run independent investigations as bounded readers in a parallel block and join their artifacts with an await, and let a participant wait through a command with its turn open.",
                    boundary:
                        "Whether a declared parallel group runs in parallel is a fact about the harness. The grammar declares that the readers are independent; the binding decides what that buys, and a harness with no concurrency runs them in order without the document changing.",
                    cause: "A sentence has an order and a graph has edges, and only the second survives being read by a party that did not write it.",
                    decision:
                        "Put the order in a graph and the lifecycle in a state machine, over numbering the units and narrating the sequence.",
                    failureMode:
                        "A sequence of decisions is numbered, one is raised out of dependency order because the next number was free, and every citation of the displaced decision resolves to the wrong thing with nothing erroring.",
                    kind: "lesson",
                    principle: "Concurrency and event ordering are declared structure, never implied by textual order.",
                    problem:
                        "Ordering implied by the order sentences appear in is reconstructed by every reader, differently.",
                    validation:
                        "Reorder the sentences of a node and re-run it. Where the outcome changed, the ordering was carried by prose, and the repair is the construct that carries it explicitly.",
                },
                {
                    kind: "text",
                    text: "A dependency graph is the construct for work whose order is a set of edges rather than a line. A node names what it depends on and what succeeds it, and the successor is declared by name, never derived from a position, for the reason the board and the venue gives. A directed acyclic graph makes a circular dependency a defect the reader can see, and where a unit holds every other party's work, at most one such unit is open at a time, because two holds are two waits with no defined order between them.",
                },
                {
                    kind: "text",
                    text: "A finite state machine is the construct for a lifecycle, and its states are a closed set because a mechanism can join on a value from a closed set and cannot join on a sentence. A unit moves forward along its states as it lives and never backwards, with one correction permitted where an act is reversed before anything depends on it. The current state is a derived state, a function over the tree, and no party writes it. Declarative configuration of a run is what both constructs are, where a paragraph would only imply it.",
                },
                {
                    kind: "text",
                    text: "A parallel block with an await is the construct for readers that return: a party spawned with a task, receiving nothing shared, returning exactly one typed artifact. Investigations that read a tree and write nothing belong there, one per concern, because reading contends with nothing. A wait is the construct for a participant, which never returns; posting and waiting are one operation for it, and a wait is a call rather than a halt. The two constructs are not interchangeable: an await joins a reader that was always going to end, and a wait keeps open a reader that must not.",
                },
                { code: DAG_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "dependency graph" },
                { code: MACHINE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "state machine" },
                { code: PARALLEL_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "join and wait" },
                { caption: "prose or construct", kind: "mermaid", text: DECLARED_DIAGRAM },
                { caption: "name, never number", kind: "mermaid", text: ORDINAL_DIAGRAM },
            ],
            title: "Structure is declared",
        },
    ],
    title: "Orchestration as declared structure",
};