import { ENCODING_SECTION_ICON } from "#configuration/icons/methodology.start.icons";
import { ENCODING_SECTION_ID } from "#core/ids/methodology.start.ids";
import type { Section } from "#types/document.types";

const ENCODING_DIAGRAM =
    'flowchart TB\n    subgraph mechanical["Mechanical rules · what the tree must be"]\n        checks["Checks, fixers, validators, generators"]\n    end\n    subgraph behavioural["Behavioural rules · how the agent works"]\n        policy["One-line rules with stable names"]\n    end\n    subgraph context["Context architecture · what the agent knows and where"]\n        cores["Agnostic cores · ontologies, templates, the standard"]\n        adapter["One adapter · binds every slot to this tree"]\n        digests["Digests · one concern each, expanding a rule"]\n        memory["Memory · one fact per file, reference never authority"]\n    end\n    tree["The tree"]\n    checks -- findings, healed or not --> policy\n    policy -- a correction hardens into a rule --> policy\n    policy -- a pattern stated twice becomes a check --> checks\n    cores -- read through --> adapter\n    adapter -- resolved slots --> policy\n    digests -- expand --> policy\n    memory -. recalled, then verified against .-> tree\n    checks -- read and heal --> tree\n    policy -- edits --> tree';

const PRECEDENCE_DIAGRAM =
    'flowchart TB\n    policy["The behaviour policy"]\n    contract["The codebase contract"]\n    boundary["A member\'s own boundary document"]\n    digests["The per-concern digests"]\n    canon["The document canon"]\n    source["Source files"]\n    memory["Memory"]\n    tree["The tree on disk"]\n    policy --> contract --> boundary --> digests --> canon --> source --> memory\n    tree -. wins over every document, and the document is fixed the same turn .-> policy';

const ENCODING_SECTION: Section = {
    icon: ENCODING_SECTION_ICON,
    id: ENCODING_SECTION_ID,
    intro: "Discipline is encoded three ways, and the three feed each other in a loop, as <cite>three encodings</cite> draws. A method with only one of the three is a method that leaks through the other two, and when two surfaces disagree a reader walks the order <cite>precedence</cite> draws.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Keep the three encodings in three homes with one scope each. Put a constraint on the tree into a check. Put a constraint on the agent's conduct into the policy as one line with a stable name. Put what the agent needs to know into the context architecture, layered so that the agnostic part transfers and the bound part is one file. Let a fact live in exactly one of the three and let the others point at it.",
                    boundary:
                        "The split is by scope, never by how important a rule feels. A behavioural rule that can be observed in an artifact is a mechanical rule wearing prose, and moving it to a check is the work rather than a demotion.",
                    cause: "A rule stated where nothing reads it is a rule held by memory, and a rule stated in two homes is two rules that drift.",
                    decision: "Classify every rule to one encoding before writing it down.",
                    failureMode:
                        "A rule about the tree sits in the behaviour policy, the agent follows it faithfully for a session, and the tree drifts anyway because nothing outside the conversation reads that sentence.",
                    kind: "lesson",
                    principle:
                        "Mechanical rules, behavioural rules and context architecture each hold one kind of discipline, and each defers to the tree.",
                    problem:
                        "Discipline written as one long instruction document mixes what a check should hold with what a person should remember, and both halves decay at the rate of the weaker one.",
                    validation:
                        "Take any rule and name its home. A rule you cannot place in one of the three is either two rules or a rule nothing enforces.",
                },
                {
                    kind: "text",
                    text: "Mechanical rules are the constraints a check can decide from the tree alone: where a file may live, what a name may say, which imports cross a boundary, whether a fact is declared twice, whether a document's references resolve. They are policy as code, held by checks, fixers, validators and generators as static analysis and fitness functions; they return pass or fail, and they run in one chain, which is what the gate holds the line means. The person is not in this encoding at all, which is the point. A mechanical rule that needs a person is a behavioural rule wearing a check's clothes.",
                },
                {
                    kind: "text",
                    text: "Behavioural rules are the constraints on how the agent works when no artifact can observe the act: that it reads a file before claiming what it holds, that it asks before the dependent work rather than after, that it never runs a step whose output it will not read whole. Each is one line with a stable name, the shape rules with names describes, so a correction has a place to land and a citation has a target.",
                },
                {
                    kind: "text",
                    text: "Context architecture is how the other two reach the agent the same way every time. The cores are agnostic: an ontology of readings, a principle canon that principles are typed describes, the naming standard that placement is a grammar describes, and the core templates the grammar page publishes. The cores are agnostic and one adapter binds them, as the drop-in explains. The digests expand one concern each where a rule needs room. Memory holds one fact per file and is reference rather than authority, so a recalled fact is verified against the tree before it is acted on. A precedence order runs through all of it, and every layer defers to the tree: a document that disagrees with the disk is wrong, and it is corrected the turn the disagreement is seen.",
                },
                {
                    kind: "text",
                    text: "The loop between the three is what makes the system cohere rather than merely coexist. A check raises a finding and the agent repairs it under the behavioural rules. A correction I give hardens into a behavioural rule and a memory the turn it arrives. A behavioural rule stated twice for the same shape is the trigger to build the check that makes it mechanical, at which point the prose becomes a pointer and the rule has a single source of truth. The cores stay untouched through all of that, because nothing in them named this tree, and the adapter absorbs whatever changed.",
                },
                { caption: "three encodings", kind: "mermaid", text: ENCODING_DIAGRAM },
                { caption: "precedence", kind: "mermaid", text: PRECEDENCE_DIAGRAM },
            ],
            title: "One kind of discipline per home",
        },
    ],
    title: "Three encodings",
};

export const ENCODING_SECTIONS: readonly Section[] = [ENCODING_SECTION];