import {
    DERIVED_SECTION_ICON,
    DETERMINISM_SECTION_ICON,
    DUPLICATE_SECTION_ICON,
} from "#configuration/icons/derivation.icons";
import { DERIVED_SECTION_ID, DETERMINISM_SECTION_ID, DUPLICATE_SECTION_ID } from "#core/ids/derivation.ids";
import type { Section } from "#types/document.types";

const AXIS_DIAGRAM =
    'flowchart TB\n    det["Deterministic · one correct answer exists"]\n    heal["Healable · a fixer can restore it"]\n    enforce["Enforceable · a check can hold it"]\n    predict["Predictable · a reader can predict it"]\n    scale["Scalable · a hundred consumers agree on it"]\n    det --> heal\n    det --> enforce\n    det --> predict\n    det --> scale';

const SUBJECT_DIAGRAM =
    'flowchart TB\n    mechanism["A mechanism is proposed"]\n    subject{"Is the subject deterministic?"}\n    build["Build the check and its healer"]\n    change{"Can the subject be made deterministic?"}\n    work["Change the subject · an act nothing records becomes an act a writer records"]\n    conduct["Declare it unobservable, with the evidence a check would need"]\n    mechanism --> subject\n    subject -- yes --> build\n    subject -- no --> change\n    change -- yes --> work --> build\n    change -- no --> conduct';

const STATE_DIAGRAM =
    'flowchart TB\n    tree["The tree on disk"]\n    traverse["A traversal, every time"]\n    state["The current state"]\n    written["A status written last week"]\n    reader["The reader"]\n    tree --> traverse --> state --> reader\n    written -. read as the present .-> reader\n    tree -. changed since .- written';

const COPIES_DIAGRAM =
    'flowchart TB\n    dup["Two copies of one fact"]\n    collapse{"Is either derivable from the other?"}\n    reduce["One declaration, one derivation · the divergence becomes unrepresentable"]\n    count{"How many claim to be the source?"}\n    one["One · a source exists"]\n    zero["Zero · a cycle, each points at another"]\n    many["Many · an undecided choice"]\n    derive["Make every other copy a derivation"]\n    declare["Declare one home and break the cycle"]\n    decide["Decide, then derive"]\n    period{"How often does the derivation run?"}\n    record["A record"]\n    stale["Drift"]\n    dup --> collapse\n    collapse -- yes --> reduce\n    collapse -- no --> count\n    count -- one --> one --> derive\n    count -- zero --> zero --> declare\n    count -- many --> many --> decide\n    derive --> period\n    period -- often --> record\n    period -- never --> stale';

const DETERMINISM_SECTION: Section = {
    icon: DETERMINISM_SECTION_ICON,
    id: DETERMINISM_SECTION_ID,
    intro: "Determinism is the one axis the others hang from, as <cite>the four properties</cite> draws. Deterministic means healable, enforceable, predictable and scalable, and pursuing those four separately produces mechanisms with none of them; predictability, repeatability and reproducibility are the ontology's names for what falls out of it. So the first question a mechanism answers is not whether its subject can be checked but whether its subject is deterministic, and <cite>the first question</cite> draws what follows from each answer. The architecture page carries the consequence for a system's size: scale follows determinism.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Ask of every mechanism whether one correct answer exists for it. Where it does, build the mechanism to produce that answer and nothing else, with its healer beside it. Where it does not, ask whether the subject can be changed so that one does, and change the subject rather than loosening the check. Where neither holds, say so and keep a person in the loop, with the evidence a check would need written down.",
                    boundary:
                        "The model's output is not deterministic and no instruction format makes it so; the author is probabilistic, as the architecture page puts it. Structure the input, then verify the output. A rule is often one deterministic half and one that is not, and the honest form names which is which.",
                    cause: "Nobody can check, heal or trust a mechanism with two possible answers at scale, because every consumer has to handle both.",
                    decision:
                        "Treat determinism as the property to reach for first, before speed and before elegance of any kind.",
                    failureMode:
                        "A check passes on one machine and fails on another, and the team learns to re-run it until it passes.",
                    kind: "lesson",
                    principle:
                        "Determinism is the axis. Healable, enforceable, predictable and scalable follow from it.",
                    problem:
                        "Most of what looks like a tooling problem is a non-determinism problem wearing a tooling costume.",
                    validation:
                        "Run the mechanism twice on the same input. Compare the bytes. A difference is a finding, whatever the tool says about itself.",
                },
                {
                    kind: "text",
                    text: "Each of the four derived properties fails in a recognisable way when determinism is missing. A healer over a judgement call guesses. A check over a non-deterministic subject either saturates or flakes. A verdict that depends on who ran it cannot be quoted. A protocol resting on care multiplies its cost by the number of parties while its enforcement stays flat. Every one of those is the same defect, and naming determinism as the source is what makes the four testable with one question.",
                },
                {
                    kind: "text",
                    text: "Changing the subject is the move most often missed. An act nothing records is not checkable; the same act performed through a tool that records it is, which is what tools live in the tree is for. A rule that a reader must remember is not checkable; the same rule as a declaration a mechanism resolves is. The rule does not change a word in either case. What changes is the subject, from a thing that happens in a turn to a thing that leaves an artifact, and once it leaves an artifact the check, the healer and the verdict all follow.",
                },
                { caption: "the four properties", kind: "mermaid", text: AXIS_DIAGRAM },
                { caption: "the first question", kind: "mermaid", text: SUBJECT_DIAGRAM },
            ],
            title: "Four properties, one axis",
        },
    ],
    title: "One correct answer",
};

const DERIVED_SECTION: Section = {
    icon: DERIVED_SECTION_ICON,
    id: DERIVED_SECTION_ID,
    intro: "Nobody writes the state of the work. Every reader derives it by looking, every time, at what is on disk, the one of the two routes <cite>two routes</cite> draws that passes through the tree. A checkbox someone ticked is a claim. A report a run wrote is evidence. A count someone typed is a copy of a fact the tree derives, wrong from the first change nobody propagated. Self-describing architecture is the property this reaches for, the health test a system is a graph names; here introspection over the tree replaces every written status.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Derive counts, statuses and progress by traversal. Write them nowhere. Keep history in exactly one place, and keep it out of the documents that state what is true now. Delete a superseded statement rather than marking it, and let a document that states how many of something exist be regenerated rather than authored.",
                    boundary:
                        "A prior value a mechanism consumes to compute a change is an operand, not history. A drift detector needs both states, and the earlier one lives in the artifact the comparison produces and goes when the comparison goes. The test is whether removing the comparison would leave the value still written.",
                    cause: "Nothing re-reads a marker after the tree moves, so its staleness has no observer.",
                    decision: "Pay the traversal on every read rather than the staleness on every write.",
                    failureMode:
                        "The plan says three of five phases are done. Two of the three were undone by a later change. The plan still says three.",
                    kind: "lesson",
                    principle:
                        "The state derives from the tree, and nobody writes it. History has its own homes and the current truth has another.",
                    problem: "Markers written into a plan describe the past and get read as the present.",
                    validation:
                        "Delete the written status and derive it again. If the derived value differs from the written one, the written one was already lying.",
                },
                {
                    kind: "text",
                    text: "Written into the plan, a status reads <em>phase three of five, done, updated last week</em>. Derived from the tree, it reads <em>phase three of five, two tasks open, one closed since the last run</em>. The first was true once. The second is true now. The difference is not diligence: a written marker goes stale by construction, and a stale marker manufactures a false belief where an absent one reads as absence.",
                },
                {
                    kind: "text",
                    text: "The same rule reaches documents. Every document states what is true now. No change notes, no renamed-from clauses, no dates tied to our own actions, no explanation of a current state in terms of a former one. History has two homes and no third: an accumulator a mechanism can read, and the message a person receives. Documentation is code makes the rule a check.",
                },
                { caption: "two routes", kind: "mermaid", text: STATE_DIAGRAM },
            ],
            title: "Derived, never written",
        },
    ],
    title: "Derived state",
};

const DUPLICATE_SECTION: Section = {
    icon: DUPLICATE_SECTION_ICON,
    id: DUPLICATE_SECTION_ID,
    intro: "A fact stated in more than one place is not yet a defect; DRY names the aim and a dual write names the failure, and the walk below decides which one a given pair is. What decides its disposition is a walk with an order, the one <cite>the walk</cite> draws: whether the copies collapse, how many of them are distinguished, at what period the derivation runs, and which consumer each copy reaches. Walked out of order the same set yields a repair that destroys evidence or a comparator over an edge that cannot exist.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Ask collapse first: where one copy is derivable from the other, stop authoring the derivable one and the divergence becomes unrepresentable. Only where collapse is unavailable, count the distinguished copies and resolve one to a derivation, zero to a declaration, and many to a decision. Then read the period of every derivation edge, because a copy that is regenerated is a stale instance and a copy fixed once at creation is a record. Last, ask what each copy reaches, because a set of copies can be fully collapsed and still deliver nothing.",
                    boundary:
                        "A one-shot copy, authored once against the fact as it stood, is a record rather than a stale instance. Collapsing it destroys evidence instead of removing duplication, so the repair inverts: diagnose the copies and repair the source.",
                    cause: "Copying never records which copy was the original, so the walk has to count.",
                    decision:
                        "Decide every duplicate by its collapse, its distinguished-copy count, its derivation period and its delivery, in that order.",
                    failureMode:
                        "Two configs disagree. Each team believes theirs is the source. Both get edits. Neither derives from the other.",
                    kind: "lesson",
                    principle:
                        "A duplicate resolves by counting its distinguished copies, and the period of the derivation decides whether a copy is a record or a stale one.",
                    problem: "Deciding which of two copies is right is guesswork until you count.",
                    validation:
                        "For a duplicated fact, name the source and the period at which the copies refresh. A copy whose refresh nothing schedules is stale from the first change to its source.",
                },
                {
                    kind: "text",
                    text: "The zero-source refusal is the directed acyclic graph ruling in the form a duplicate reaches it. A second declaration is an edge rather than a fact beside the first, so a set of copies is a dependency graph and its collapse is a direction along it; a cycle among them is a circular dependency between facts. Where no copy is distinguished the graph has no root, and a collapse would have to choose one the structure does not supply. Refusing is the whole of the correct behaviour there, and it is the part a builder is most tempted to improve: a tiebreak fired over a cyclic set converts a correct refusal into a confident wrong answer.",
                },
                {
                    kind: "text",
                    text: "Every divergence repair asks which side is authoritative first. A join reports that two declarations agree and can never report that the agreed value is right. Where one side cites the other, the direction is forced and the repair is bookkeeping. Where both sides declare, a decision is being taken about which value is correct, and the gradient runs toward whichever side is free to change, so converging on the cheap side and reporting it as maintenance is the substitution to refuse. A comparison's green is a correctness verdict only where one operand is authoritative, and elsewhere it says two things match without saying either is right.",
                },
                { caption: "the walk", kind: "mermaid", text: COPIES_DIAGRAM },
            ],
            title: "Count the distinguished copies",
        },
    ],
    title: "Counting copies",
};

export const DERIVATION_SECTIONS: readonly Section[] = [DETERMINISM_SECTION, DERIVED_SECTION, DUPLICATE_SECTION];