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

const CLASS_SAMPLE =
    "# the reader class is derived from what a document receives · its terminal node says which\n\n# NODE 10 — TERMINATE   [evaluative · termination · set-theory · yields: ter-stop boolean]\n# a participant · receives what it owns and what is addressed to it, and never returns\nCONTRACT:\n  input:        <items addressed to me> + <open units of my own concern>\n  transform:    handle what is addressed to me -> perform my own clear work -> WAIT on the shared surface -> re-enter\n  constraints:  ter-stop is the person's call; a quiet wait is a fact about the peers, never about the queue\n  output:       nothing terminal · the loop re-enters at NODE 1\n  handoff:      <changed> -> NODE 1 ORIENT (read the surface whole, then act) | <quiet> -> my own work, then WAIT again\n\n# NODE 10 — TERMINATE   [evaluative · termination · set-theory · yields: ter-stop boolean]\n# a bounded reader · receives a task and nothing shared, and returns exactly once\nCONTRACT:\n  input:        <the task it received>\n  transform:    evaluate saturation AND completion AND verification -> emit one typed artifact\n  constraints:  no shared surface is read, so no surface rule binds; an unresolved question is a finding with what would settle it, never a held turn\n  output:       one typed artifact | a blocked report naming what would settle it\n  handoff:      TERMINATE";

const REPAIR_SAMPLE =
    '# a finding on a surface I do not own becomes an item, never an edit · the op-set forbids it, not restraint\n\nFUNCTION emit_repair(finding):\n  IF owner_of(finding.surface) == <me>: RETURN {route: "act", change: finding.change}\n  SET item = {kind: artifact, to: [owner_of(finding.surface)], surface: finding.surface, locus: finding.locus, observed: finding.observed, expected: finding.expected, change: finding.change}\n  PERSIST_ARTIFACT item TO <the shared surface> AS <me>\n  RETURN {route: "sent", item: item}\n\n# NODE 6 — ACT   [epistemic · formalisation · computation · yields: procedures]\nCONTRACT:\n  input:        findings\n  transform:    for each finding -> emit_repair -> apply only what routes to "act"\n  constraints:  an INVESTIGATE op-set performs no mutation; a mutation on another\'s surface is a breach whatever its correctness\n  output:       applied[] + sent[]\n  handoff:      every finding either applied on my own surface or sent to its owner (yields: boolean)\n\nHANDOFF GATE (evidence-bearing):\n  rule_id: "ACT"   yields: boolean\n  [check] no applied change touched a surface I do not own (evidence: applied[].surface)\n  [check] every sent item names its owner, its locus and the one change (evidence: sent[])\n  [check] every finding routed exactly once (evidence: applied[] and sent[] partition findings)\n  result: pass -> NODE 7 | a foreign write -> REPAIR (owner: NODE 6) | unknown -> BLOCKED';

const COUNT_SAMPLE =
    "# the party count is an output of the structure, never an input to it\n\nFUNCTION derive_count(work):\n  ANALYZE_CONTENT work FOR <pairs of surfaces where a change to one forces a change to the other> INTO coupling   # yields: edge-list\n  EXTRACT_FACTS connected_components FROM coupling INTO concerns                                                 # yields: set\n  CALCULATE_METRIC floor = count(concerns)                                                                        # one party per concern\n  ANALYZE_CONTENT claims FOR <how many rest on one surface> INTO fan_in                                          # yields: number\n  CALCULATE_METRIC ceiling = <the population past which a claim is stale more often than it is useful>\n  RETURN {concerns: concerns, floor: floor, ceiling: ceiling}";

const CONTRACT_DIAGRAM =
    'flowchart TB\n    work["A body of work"]\n    concerns["Concerns that must be able to contradict each other"]\n    parties["One party per concern · each a document, none above the others"]\n    surfaces["Shared surfaces · what each owns, what is addressed to whom"]\n    owner["A change to another\'s surface travels as an item · the owner makes it"]\n    work --> concerns --> parties --> surfaces --> owner\n    parties -. nothing here .-> controller["A controller"]';

export const COMPOSITION_SECTION: Section = {
    icon: COMPOSITION_SECTION_ICON,
    id: COMPOSITION_SECTION_ID,
    intro: "A collaboration is composed from parties, and nothing sits above them, the shape <cite>parties over a partition</cite> draws. The method states the premise as coordination is software; the grammar expresses it as documents: <cite>two terminal nodes</cite> is how a document states its reader class, <cite>change across ownership</cite> how a finding travels to its owner, and <cite>party count</cite> how the count is derived rather than chosen. What a document cannot do is make the parties agree; it can only make their disagreement land where a reader can see it.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Compose a collaboration by partitioning the work into concerns that must be able to contradict each other, and give each concern one document. Let the terminal node state the reader class, so the ending is derived: a participant re-enters after a wait, a bounded reader returns one typed artifact. Route a change across ownership as an item carrying what was observed, what was expected and the one edit, and let the owner's act node be the only one that writes.",
                    boundary:
                        "One writer and one tree is not a collaboration, and the constructs here defend against a party that cannot exist there. A single document with a single reader takes none of this, and adding it is ceremony.",
                    cause: "A party that holds the order for the others is a party every other party waits on, and a design where finders also fix has parties writing a tree that other parties are still reading.",
                    decision:
                        "Derive the parties from the partition rather than assign positions, and give the order to the surfaces rather than to a controller.",
                    failureMode:
                        "A workflow names four positions before the work is examined, the work has three concerns, one position spends the run relaying between the other three, and the relay is where every message is lost.",
                    kind: "lesson",
                    principle:
                        "A collaboration is parties over a partition, coordinating through surfaces, with nothing between them.",
                    problem:
                        "A workflow written as a sequence of agents with fixed positions runs the same shape on every task, and no task has that shape.",
                    validation:
                        "Take a running collaboration and remove any one document. Where the others stall, that document was a controller; where they route around it, the composition held.",
                },
                {
                    kind: "text",
                    text: "A document's terminal node states the reader class, and the class decides what the node yields: a participant's re-enters after a wait, a bounded reader's is one typed artifact. Which class a reader is, and why the turn rules invert for one of them, is coordination is software's; a document whose terminal node states its class makes the inversion legible, and one that leaves it to the reader gets both classes' rules applied at once.",
                },
                {
                    kind: "text",
                    text: "Ownership is what replaces the controller. Scope is claimed by concern rather than by location, because two parties can claim one folder from two claims that never mention each other. A finding that lands on a surface its finder does not own is a real finding and a forbidden edit at the same time, and the two rules are reconciled by kind rather than by restraint. The finder's act node emits an item with the surface, the locus, what it observed, what it expected and the one change, and the owner makes it. The finder's operation set forbids the mutation, and its handoff gate carries the evidence that nothing it applied touched a surface it does not own, so the collision between fix-on-sight and untouchable scope has a structural answer instead of a careful one.",
                },
                {
                    kind: "text",
                    text: "The count is an output, and the function that derives it is what a document carries instead of a number. The floor is one party per concern, as a concern is a component derives. The ceiling is where a stale claim costs more than one more perspective buys, as the ceiling moves by cost derives.",
                },
                { code: CLASS_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "two terminal nodes" },
                { code: REPAIR_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "change across ownership" },
                { code: COUNT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "party count" },
                { caption: "parties over a partition", kind: "mermaid", text: CONTRACT_DIAGRAM },
            ],
            title: "Parties over a partition",
        },
    ],
    title: "Composing a collaboration",
};