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

const SCHEMA_SAMPLE =
    "# the four things a document declares about a shared surface · a structure declaration, never prose\nSURFACE <key>:                                   # declared in the header, never derived from the path\n    RECORD <key>-1 subject: <what it is about>   # one writer, named on the record · the fence an edit anchors on\n        ITEM <key>-1-1 TO <reader>: <a claim>    # an addressed span · its id allocated once, never reused\n            SATISFIED_BY <artifact>              # an edge · an id in a field · resolves or does not\n            BLOCKS <key>-2-1\n    RECORD <key>-2 subject: <what it is about>\n        ITEM <key>-2-1 TO <reader>: <a claim>\n            ANSWERS <key>-1-1\n\n# the states are derived from the edges, never written\nstate: OPEN | BLOCKED | ABSORBED\n\n# the lifetime, declared on three axes a mechanism can join on\nDECLARE lifetime: object\nSET lifetime = {retention: <what ends a piece of content>, mutability: <who may rewrite a landed statement>, removal: <who may take content out>}";

const STATE_SAMPLE =
    '# no party writes a state · every state is a function over the edges, evaluated on every read\nFUNCTION state_of(item):\n  IF resolves(item.edges.satisfied_by): RETURN <absorbed>       # a transition · extract, then delete in the same change\n  FOR EACH edge IN inbound(item, <blocks>):\n    IF state_of(edge.from) == <open>: RETURN <blocked>\n  RETURN <open>\n\n# NODE 6 — ACT   [epistemic · formalisation · computation · yields: procedures]\nCONTRACT:\n  input:        <my record> + <the surface as it stands>\n  transform:    read the surface whole -> anchor on my own fence -> land the edit inside it\n  constraints:  a write to a path not read this turn is an edit to unknown contents; a whole-file write reports success to the one who overwrote and nothing to the one overwritten\n  output:       <my record, revised>\n  handoff:      the edit landed inside my fence and the surface had not moved, or the edit was refused with the diff (yields: boolean)\n\nHANDOFF GATE (evidence-bearing):\n  rule_id: "ACT"   yields: boolean\n  [check] nothing outside my fence changed (evidence: the diff of the surface) over: the surface\'s records measured: <untouched> / <records>\n  [check] the surface was read whole immediately before the write (evidence: the witness read)\n  [check] a moved surface refused the write, or the write commuted and replayed (evidence: the compare against my own span)\n  refuse: the surface moved inside my span since the witness read before PERSIST_ARTIFACT\n  standing: moved-set <the records that moved outside my span>\n  result: pass -> NODE 7 | a write outside my fence -> REPAIR (owner: NODE 6) | unknown -> BLOCKED';

const LIFETIME_SAMPLE =
    "# a lifetime is three independent axes · one word for it drops the axis a reader assumes follows\nDECLARE lifetimes: array\nSET lifetimes = [\n  {surface: <a coordination surface>, retention: <current-truth>,  mutability: <owner-rewritable>, removal: <the handler of an item>},\n  {surface: <an argument>,            retention: <accumulating>,   mutability: <append-only>,      removal: <none while open · moved whole when settled>},\n  {surface: <an archive>,             retention: <accumulating>,   mutability: <frozen>,           removal: <none>}\n]\n\nFUNCTION may_remove(party, content, surface):\n  # decided from the declaration, never from the shape of the path\n  SET lifetime = lifetimes[surface]\n  RETURN lifetime.removal == party.role_on(content)";

const RECORD_DIAGRAM =
    'flowchart TB\n    surface["A surface · a file the parties read and write"]\n    r1["Record · one writer, declared on the record"]\n    r2["Record · one writer"]\n    item["Item · an allocated id, a kind, its readers"]\n    ref["An edge · an id in a field · resolves or does not"]\n    state["State · a function over the edges, written by nobody"]\n    surface --> r1\n    surface --> r2\n    r1 --> item --> ref --> state';

const WRITE_DIAGRAM =
    'flowchart TB\n    intent["A party intends a write"]\n    read["Read the surface whole"]\n    span["Anchor on its own fence"]\n    moved{"Surface moved since the read?"}\n    land["Land inside the span"]\n    overlap{"Overlap with its own span?"}\n    replay["Replay · the writes commute"]\n    refuse["Refuse · with the diff of the span"]\n    intent --> read --> span --> moved\n    moved -- no --> land\n    moved -- yes --> overlap\n    overlap -- no --> replay --> land\n    overlap -- yes --> refuse';

export const CONSTRUCT_SECTION: Section = {
    icon: CONSTRUCT_SECTION_ICON,
    id: CONSTRUCT_SECTION_ID,
    intro: "When more than one party writes one tree, the surfaces they share are shared mutable state, and a document expresses four things about them: the schema, the records, the items and their lifetime, which <cite>surface declared</cite> writes and <cite>surface to state</cite> draws. The definitions and the reasons are coordination is software's and the board and the venue's; this section declares the shape: <cite>state as function</cite> is how a state is read and a write fenced, <cite>a write lands</cite> is where a write lands or refuses, and <cite>lifetime axes</cite> is the declaration a mechanism reads.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Declare a shared surface as a schema: its key in its header, one record per writer with the writer named on the record, and a fence around each record so an edit has a span to anchor on. Declare an item with an id the surface allocates, a kind that selects its closure, and the readers it is addressed to. Derive open, blocked and absorbed by a function over the edges, extract an absorbed item's durable half and delete it in the same change, and declare each surface's lifetime on retention, mutability and removal.",
                    boundary:
                        "An outcome surface authored jointly has no per-party unit for one writer per record to range over, so the invariant is declared inapplicable there with its reason, and a collision of meaning there is reached by an announcement of the intended write plus each author cutting its own duplicate.",
                    cause: "A file offers no span a party can anchor on unless the document declares one, so the only edit available is the whole file.",
                    decision:
                        "Declare the surface as a schema a tool can refuse against, rather than describe it in prose the parties keep in mind.",
                    failureMode:
                        "Two parties revise their own records by rewriting the file, each correctly, and the second write is a lost update for the first party with no error anywhere.",
                    kind: "lesson",
                    principle:
                        "A shared surface holds records with one writer each, and every state is a query over them.",
                    problem:
                        "A shared document with no declared writer per span is a document every party rewrites whole.",
                    validation:
                        "Take the last write to a shared surface and name the span it was anchored on. A write with no span was a whole-file write, and the neighbour it overwrote is the finding.",
                },
                {
                    kind: "text",
                    text: "The document states one writer per record on the record. The act node that writes carries the mechanism as its contract, a witness read, an anchor on its own fence and a refusal when the surface moved, so an edit against a moved surface is refused with the diff and a whole-file write is never the available path.",
                },
                {
                    kind: "text",
                    text: "The document writes no state. Every state is a function over the edges, declared once and evaluated on every read, as derived state teaches, and an item whose citation resolves is extracted and deleted in the same change rather than left resting in a state.",
                },
                {
                    kind: "text",
                    text: "A lifetime is declared on the three axes stating an invariant derives, each drawn from a closed set, so the declaration is an operand a mechanism can join on rather than a sentence. A mechanism decides what it may do to a surface from that declaration and never from the shape of its path.",
                },
                { code: SCHEMA_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "surface declared" },
                { code: STATE_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "state as function" },
                { code: LIFETIME_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "lifetime axes" },
                { caption: "surface to state", kind: "mermaid", text: RECORD_DIAGRAM },
                { caption: "a write lands", kind: "mermaid", text: WRITE_DIAGRAM },
            ],
            title: "Records, items, derived states",
        },
    ],
    title: "Shared surfaces",
};