import { AGENT_SECTION_ICON, HUMAN_SECTION_ICON } from "#configuration/icons/coordination.icons";
import { AGENT_SECTION_ID, HUMAN_SECTION_ID } from "#core/ids/coordination.ids";
import type { Section } from "#types/document.types";
import { stageLink as stage } from "#domain/converters/link.converter";

const HUMAN_DIAGRAM =
    'flowchart TB\n    operator["The operator"]\n    ai["The AI"]\n    tree["The tree"]\n    operator -- what the work is for, what finished means --> ai\n    operator -- a correction, brief, once --> ai\n    ai -- the shape of the work --> tree\n    ai -- a question through one channel, recommendation first --> operator\n    ai -- the correction hardened into a rule and a memory --> tree\n    tree -- read whole, every session --> ai\n    operator -. calls the stop .-> ai';

const AGENT_DIAGRAM =
    'flowchart TB\n    anchor["Disclose the trust anchor · what is assumed and cannot be verified"]\n    phase["Bind to one phase · investigate discovers and never fixes, action fixes and never discovers"]\n    rank["Rank the claims by verification worth"]\n    calibrate["Calibrate every detector · a known-good it must match, a known-bad it must not"]\n    resolve["Resolve each claim to the observation that would settle it"]\n    gather["Gather from the implementation · never infer"]\n    admissible["Check the phase was honoured"]\n    verify["Classify each claim · verified, contradicted, unverified"]\n    audit["Audit the agent\'s own contract · an overclaim lowers its confidence"]\n    artifact["Emit exactly one typed artifact"]\n    anchor --> phase --> rank --> calibrate --> resolve --> gather --> admissible --> verify --> audit --> artifact\n    verify -. refuted or escalated, bounded .-> resolve';

const CREATION_DIAGRAM =
    'flowchart TB\n    evidence["Inspected domain evidence"]\n    contract["A portable contract · semantic operations and slots, no runtime"]\n    adapter["An adapter renders it for one runtime"]\n    grounded{"Grounded, embodied, no leakage?"}\n    persisted["Persisted, with its participation declared in the body"]\n    evidence --> contract --> adapter --> grounded\n    grounded -- yes --> persisted\n    grounded -- no --> contract';

const HUMAN_SECTION: Section = {
    icon: HUMAN_SECTION_ICON,
    id: HUMAN_SECTION_ID,
    intro: "The line ask where it appears draws, what the work is for against the shape of the work, is crossed in two directions and only two, as <cite>two channels</cite> draws: a question travels up through one channel with a recommendation first, and a correction travels down once and hardens into rules with names. Everything else the two need to know, they read from the tree. Who does what states the same split with the tooling as the third party, and the architecture page grounds it in what the author is: probabilistic.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Govern by writing what the work is for and what finished means, and correct drift immediately and briefly, in a few words, once. Expect the correction to become a rule with a stable name and a memory the same turn, and expect the next session to read them. Halt on any statement of yours that contradicts the plan, re-verify, and report rather than argue file state. Let a session run continuously until the queue is empty, and call the stop yourself.",
                    boundary:
                        "A question crosses the line only when its answer changes what gets built, and then before the dependent work.",
                    cause: "A model optimises for the reply that reads as helpful, and a reply that reads as helpful is a summary, a pause offered as thoroughness, or a question that could have been a recommendation.",
                    decision:
                        "Cross the line through the two channels only, a question up and a correction down, rather than through the conversation.",
                    failureMode:
                        "The person explains the architecture at length, the AI reports a milestone and asks what to do next, and the work stops while looking finished.",
                    kind: "lesson",
                    principle:
                        "The human governs, the AI executes inside the boundaries, and a correction hardens rather than repeats.",
                    problem:
                        "Without a declared split, the person ends up shaping the work by hand and the AI ends up guessing what it was for.",
                    validation:
                        "Read a session's transcript for the moments the turn ended. Each is either the person calling the stop, a question through the channel, or a halt wearing a report's clothes.",
                },
                {
                    kind: "text",
                    text: "The AI never surfaces, implies or acts on its own remaining capacity, because it cannot measure it and an assumption presented as a constraint is a lie that truncates the work. Only the human calls the stop, and a turn never ends to wait names the halts that pretend otherwise.",
                },
                {
                    kind: "text",
                    text: "A stale memory triggers a question rather than a silent refresh; three encodings holds the precedence.",
                },
                { caption: "two channels", kind: "mermaid", text: HUMAN_DIAGRAM },
            ],
            title: "Two channels across one line",
        },
    ],
    title: "The human and the AI",
};

const AGENT_SECTION: Section = {
    icon: AGENT_SECTION_ICON,
    id: AGENT_SECTION_ID,
    intro: `A persisted agent is a walked loop, not a persona, the loop <cite>a verifying agent</cite> draws; the agent templates on the grammar page are walked, not adopted, and a seat is a contract is the same rule for a seat, and an agent comes to be as <cite>making an agent</cite> draws. Its definition is executed rather than consulted: it discloses what it trusts, binds itself to one phase as phase binding requires, ranks what is worth verifying, calibrates its detectors, gathers from the implementation, checks its own contract against its own behaviour, and emits exactly one typed artifact. The agent that creates agents and the agent that audits them are the same loop applied to agents themselves, and the ontology's contracts for the ${stage("orient")} and ${stage("verify")} stages are what the walk executes.`,
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Write an agent as a contract the loop can execute. Give it a disclosed trust anchor, a phase it binds to, and a ranking of its claims by risk and uncertainty. Give every claim an evidence requirement that names the observation that would settle it, an admissibility check that the phase was honoured, and a single typed artifact at the end. Generate it from inspected evidence about its domain, render it through an adapter, and prove it is grounded and embodied before it is persisted.",
                    boundary:
                        "A bounded invocation has no channel back, so it returns its uncertainty the way ask where it appears describes, and an inverted rule is actively wrong while reading as governed.",
                    cause: "An agent written as a description is applied by its reader's interpretation, and the interpretation drifts with the reader.",
                    decision: "Define an agent by the loop it walks and the artifact it emits.",
                    failureMode:
                        "A reviewer agent with a persuasive system prompt affirms a change that reads well, because nothing in its definition made it open the diff, calibrate a detector or name what would refute its verdict.",
                    kind: "lesson",
                    principle:
                        "A capability is not real until its behaviour matches a testable contract, and a verifier applies its rules to itself.",
                    problem:
                        "An agent defined by a voice can be judged only by how it sounds, and sounding right is what a model always does.",
                    validation:
                        "Run the agent on a case with a planted contradiction and on a case that is clean. It must report the contradiction with its evidence and pass the clean case for the right reason. An agent that cannot fail on purpose has never been shown to work.",
                },
                {
                    kind: "text",
                    text: "The anchor is disclosed, as verify the verifier requires, and the self-audit is what catches the overclaim above it: the agent reads its own definition, extracts every capability it claims, runs a positive and a negative case for each, and downgrades its confidence for every claim it cannot back.",
                },
                {
                    kind: "text",
                    text: "Phase binding is what keeps an investigation honest. An investigation discovers and never fixes; its artifact is a report of evidence. An action fixes and never discovers; its artifact is a log of bounded changes against known evidence. The two are exclusive because the checks that heal rewrite the tree, so an investigation that ran them has mutated under a read-only contract.",
                },
                {
                    kind: "text",
                    text: "An agent is generated the way a plan is: from a template, executed, as execute the template describes. Its source is inspected evidence about the domain it will investigate, never prior knowledge, which is the difference between grounded output and ungrounded AI output. Its target is a portable contract, the shape the drop-in gives every core, rendered for one runtime through an adapter pattern, so the same agent ports by re-rendering. What an agent must know to act is declared in the body it is delivered with, because a declaration in a field the runtime discards reaches nobody, and a check reading that field measures an artifact while the mechanism stands inert.",
                },
                { caption: "a verifying agent", kind: "mermaid", text: AGENT_DIAGRAM },
                { caption: "making an agent", kind: "mermaid", text: CREATION_DIAGRAM },
            ],
            title: "A walked loop, one artifact",
        },
    ],
    title: "Agents as executed contracts",
};

export const COORDINATION_SECTIONS: readonly Section[] = [HUMAN_SECTION, AGENT_SECTION];