import { PAG_LANGUAGE, TEXT_LANGUAGE } from "#configuration/constants/code.constants";
import { BLUEPRINT_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { BLUEPRINT_SECTION_ID } from "#core/ids/grammar.ids";
import type { Section } from "#types/document.types";

const SURFACE_TEMPLATE =
    "template:\n  type:        PROTOCOL\n  title:       <how parties share one surface>\n  slots:\n    - name: {SURFACE_KEY}          required: true    kind: string\n    - name: {RETENTION}            required: true    enum: [<current-truth>, <accumulating>, <discharged>]\n    - name: {MUTABILITY}           required: true    enum: [<owner-rewritable>, <append-only>, <frozen>]\n    - name: {REMOVAL}              required: true    enum: [<handler>, <author>, <producer>, <none>]\n  constraints:\n    - declaration_required\n    - one_writer_per_record\n    - state_derived_never_written\n    - removal_declares_its_extraction\n  body: |\n    THIS PROTOCOL DEFINES how parties share {SURFACE_KEY}\n\n    DECLARE lifetime: object\n    SET lifetime = {retention: {RETENTION}, mutability: {MUTABILITY}, removal: {REMOVAL}}\n\n    # RULE 1: one writer per record\n    WHEN <party> writes {SURFACE_KEY}:\n        READ_RESOURCE {SURFACE_KEY} whole INTO <current>\n        EDIT {SURFACE_KEY} inside <party>.<record> only\n\n    # RULE 2: state is derived\n    WHEN a state is asked: RETURN state_of(<item>)     # a function over the edges, never a field\n\n    # RULE 3: removal declares its extraction\n    WHEN <item> is absorbed AND <party> IN <item>.<to>:\n        EXTRACT_FACTS <item>.<durable half> INTO <the one home history has>\n        REMOVE <item> BY <item>.<id>";

const VENUE_TEMPLATE =
    "template:\n  type:        PROTOCOL\n  title:       <a decision that holds the build until it converges>\n  slots:\n    - name: {QUESTION}             required: true    kind: string\n    - name: {EXIT_CONDITION}       required: true    kind: string     # checkable against the tree, never judged\n    - name: {SUCCESSOR}            required: false   kind: string     # declared by name, never derived from a number\n  constraints:\n    - declaration_required\n    - exit_condition_stated\n    - positions_accumulate_until_convergence\n    - converged_is_absorbed_before_archived\n  body: |\n    THIS PROTOCOL DEFINES how {QUESTION} is decided\n\n    # a position carries evidence or it is an opinion · it stands until read and signed\n    DECLARE position: object\n    SET position = {claim: <one line>, axis: <the design question>, evidence: <an observation anyone can reproduce>, proposes: <the mechanism>, costs: <what it makes harder, by its own author>, contradicts: <a position id, or nothing>, signed: <the author, or nothing>}\n\n    FUNCTION converged(venue):\n      RETURN every_party_stated_its_needs(venue) AND every_need_is_empty(venue) AND every_position_signed(venue) AND {EXIT_CONDITION}\n\n    # NODE 10 — TERMINATE   [evaluative · termination · set-theory · yields: ter-stop boolean]\n    CONTRACT:\n      input:        the venue + the distribution its outcome implies\n      transform:    converge -> distribute the implied work as a plan with an owner per item -> land it -> move the venue whole into the archive\n      constraints:  convergence certifies agreement and nothing about the tree; leaving the active tree and leaving the repository are different operations\n      output:       the outcome in the surviving documents, the argument in the archive\n      handoff:      absorbed (yields: boolean)";

const CHOICE_SAMPLE =
    "# the same transport, opposite lifetimes · the fields belong to the concern and never transfer\n<a coordination surface>   carries STATE     who owns what, what is directed at whom      swept · a resolved item is deleted\n<an argument>              carries POSITIONS where each party stands, what it still needs   accumulates · moved whole when absorbed\n\n# a position written onto the coordination surface is accumulation on the surface built to be swept\n# a state written into an argument is ownership described in a document about a decision";

const TEMPLATE_DIAGRAM =
    'flowchart TB\n    surface["Surface protocol · one writer per record, derived state, lifetime on three axes, extraction before removal"]\n    venue["Decision protocol · positions with evidence, an exit condition, convergence then absorption then the archive"]\n    transport["One transport · fenced records, allocated ids, compare-and-swap"]\n    surface -.-> transport\n    venue -.-> transport';

export const BLUEPRINT_SECTION: Section = {
    icon: BLUEPRINT_SECTION_ICON,
    id: BLUEPRINT_SECTION_ID,
    intro: "Two templates cover coordination between parties, <cite>surface protocol</cite> and <cite>decision protocol</cite>, and they share one transport with opposite lifetimes, the pair the board and the venue teaches and <cite>one transport</cite> draws. Each is a template record with slots drawn from closed sets, raised into an instance by resolving them, and <cite>two lifetimes</cite> shows why the fields of one never transfer to the other.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Raise a surface protocol by resolving its key and its three lifetime values from their closed sets, and keep its rules as written: read whole, write inside your own record, derive every state, extract before removal. Raise a decision protocol by stating the question and an exit condition the tree can decide, declare a successor by name where one exists, and let the closure be absorption rather than agreement. Where a slot the adapter cannot resolve is named, declare the absence rather than filling it.",
                    boundary: "A decision with one party is a choice.",
                    cause: "A description in words has no closed set a mechanism can join on, so each party implements the words it read.",
                    decision:
                        "Raise the protocol from a template whose values come from closed sets, over a description each collaboration writes fresh.",
                    failureMode:
                        "A surface is described as append-only, a mechanism implements the word faithfully, and a settled argument is deleted rather than archived because no removal axis was ever declared.",
                    kind: "lesson",
                    principle:
                        "Coordination is raised from templates whose slots are the surfaces, their lifetimes and their closures.",
                    problem: "Each collaboration describes its shared surfaces in its own words.",
                    validation:
                        "For each shared surface, name its three lifetime values and the party that may remove from it. A surface with a one-word lifetime has an undeclared axis, and the mechanism that implements the word will act on the axis it never saw.",
                },
                {
                    kind: "text",
                    text: "The surface protocol puts the lifetime first, because every later rule depends on it, and the three axes are shared surfaces'. Then one writer per record, then a state that is a function over the edges, then a removal that refuses without a reference naming where the extraction landed. The check decides presence and never fidelity, because an extraction is a compression and a text comparison would fail every correct one.",
                },
                {
                    kind: "text",
                    text: "The decision protocol declares its own exit condition or it is an indefinite halt. A position carries evidence or it is an opinion, and its author states what its own proposal makes worse, because a position nobody can attack converges by exhaustion rather than by agreement. What convergence is, and why the archive follows absorption, is the board and the venue's.",
                },
                { code: SURFACE_TEMPLATE, kind: "code", language: TEXT_LANGUAGE, title: "surface protocol" },
                { code: VENUE_TEMPLATE, kind: "code", language: TEXT_LANGUAGE, title: "decision protocol" },
                { code: CHOICE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "two lifetimes" },
                { caption: "one transport", kind: "mermaid", text: TEMPLATE_DIAGRAM },
            ],
            title: "Surface and decision",
        },
    ],
    title: "Coordination templates",
};