import {
    APPEARANCE_SECTION_ICON,
    REPORT_SECTION_ICON,
    UNKNOWN_SECTION_ICON,
    VERIFIER_SECTION_ICON,
} from "#configuration/icons/evidence.icons";
import {
    APPEARANCE_SECTION_ID,
    REPORT_SECTION_ID,
    UNKNOWN_SECTION_ID,
    VERIFIER_SECTION_ID,
} from "#core/ids/evidence.ids";
import { nodeLink as node, stageLink as stage } from "#domain/converters/link.converter";
import type { Section } from "#types/document.types";
import { TYPESCRIPT_LANGUAGE } from "#configuration/constants/code.constants";

const VERDICT_SHAPE =
    'export type Value = "pass" | "fail";\nexport type Standing = "authoritative" | "withdrawn";\n\nexport interface Stamp {\n    readonly surface: string;\n    readonly seen: string;\n}\n\nexport interface Verdict {\n    readonly value: Value;\n    readonly standing: Standing;\n    readonly reached: readonly string[];\n    readonly moved: readonly Stamp[];\n    readonly healedByThisRun: readonly string[];\n    readonly derivations: readonly Finding[];\n}\n\nexport const standingOf = (moved: readonly Stamp[]): Standing => (moved.length === 0 ? "authoritative" : "withdrawn");\n\nexport const quotable = (verdict: Verdict): boolean => verdict.value === "pass" && verdict.standing === "authoritative";';

const CLAIM_DIAGRAM =
    'flowchart TB\n    edit["An edit lands"]\n    read["The AI reads it back"]\n    story["A story about the result"]\n    run["The verifier runs"]\n    exit["An exit code and parsed findings"]\n    done{"Done?"}\n    edit --> read --> story\n    edit --> run --> exit --> done\n    story -. never the signal .-> done';

const OUTPUT_DIAGRAM =
    'flowchart TB\n    output["A message printed by a run"]\n    subject{"Is its subject the mechanism that printed it?"}\n    report["A report · the authority of an execution"]\n    prose["Prose · opened at the mechanism it names, never trusted for arriving as output"]\n    output --> subject\n    subject -- yes --> report\n    subject -- no --> prose';

const CONTROL_DIAGRAM =
    'flowchart TB\n    written["A check is written"]\n    real["A real case it passes"]\n    planted["A planted case it fails"]\n    adversarial["Adversarial inputs it rejects"]\n    self["The tooling passes through its own gate"]\n    recorded["The first firing and the first clearing are recorded"]\n    trusted["Trusted, above a disclosed anchor"]\n    written --> real --> planted --> adversarial --> self --> recorded --> trusted';

const STANDING_DIAGRAM =
    'flowchart TB\n    run["A run reads its surfaces and stamps each"]\n    restamp["It re-stamps them at the end"]\n    moved{"Did any surface move beneath it?"}\n    authoritative["The verdict stands and may be quoted"]\n    withdrawn["The verdict keeps its value and loses its standing · the moved set is named"]\n    run --> restamp --> moved\n    moved -- no --> authoritative\n    moved -- yes --> withdrawn';

const VERDICT_DIAGRAM =
    'flowchart TB\n    surface["A surface a unit can fail in"]\n    tested{"Does a test touch it?"}\n    passed{"Did it pass?"}\n    pass["Pass"]\n    fail["Fail"]\n    unknown["Unknown · never rounds up to pass"]\n    surface --> tested\n    tested -- no --> unknown\n    tested -- yes --> passed\n    passed -- yes --> pass\n    passed -- no --> fail';

const APPEARANCE_SECTION: Section = {
    icon: APPEARANCE_SECTION_ICON,
    id: APPEARANCE_SECTION_ID,
    intro: `The most expensive failures I have had were the ones that looked right. The code read well. The AI said it was done. Nothing had run. Everything in this chapter follows from one distinction: a claim is a sentence a party produced, ungrounded AI output until something grounds it, and ${node("ver-evidence", "evidence")} is an observation a mechanism produced, and only the second decides anything, which is what <cite>a claim's source</cite> draws and <cite>report and prose</cite> separates. The ${stage("verify")} node of the loop asks exactly this, and the ontology's verification axis names its parts: ${node("ver-ground-truth", "ground truth")}, ${node("ver-falsification", "falsification")}, ${node("ver-confidence", "confidence")} and ${node("ver-refutation", "refutation")}.`,
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Take the exit code as the answer. Take the parsed findings as the answer. Take the AI's summary as a story about the answer.",
                    boundary:
                        "A mechanism's output is evidence about itself and prose about its neighbours. The sentence most likely to stop a reader looking further is one whose subject is not its own emitter, because it appears to have already done the looking.",
                    cause: "A model produces text that resembles a finished result, because that is what finished results look like in its training.",
                    decision: "Let the report on disk decide done, rather than the reply that describes it.",
                    failureMode:
                        "Compliance claimed after one edit, never re-verified, and the next run of the tools finds the same fault plus a new one.",
                    kind: "lesson",
                    principle: "The machine derives the verdict. A model's judgement is never the completion signal.",
                    problem: "An AI judges its own edit as clean by reading it, and reading is not running.",
                    validation:
                        "Find the verifier output behind every done claim in a session. A done with no output behind it is a claim, and a claim is unverified.",
                },
                {
                    kind: "text",
                    text: "A completion claim reads <em>all done, the change is clean and everything passes</em>. A completion signal reads <em>gate: every step passed, exit zero, report written to the run's path</em>. The first is a sentence a model produced. The second is a number a machine produced.",
                },
                {
                    kind: "text",
                    text: "Evidence has tiers, and they are ranked. A measurement taken locally outranks a vendor's documentation, which outranks a community source, which outranks inference. A record carries its confidence and its derivation as two separate axes, because material adapted from elsewhere can be strong or weak evidence independently of having been adapted, and pushing a provenance word into the strength vocabulary leaves the whole set unrankable. Conflicting sources are both recorded and the conflict is stated. An unverified or single-sourced claim is labelled as such wherever it drives a decision.",
                },
                { caption: "a claim's source", kind: "mermaid", text: CLAIM_DIAGRAM },
                { caption: "report and prose", kind: "mermaid", text: OUTPUT_DIAGRAM },
            ],
            title: "Looks right is not runs right",
        },
    ],
    title: "It looked right",
};

const VERIFIER_SECTION: Section = {
    icon: VERIFIER_SECTION_ICON,
    id: VERIFIER_SECTION_ID,
    intro: "Verification is evidence, and the verifier itself gets verified, in the order <cite>earning trust</cite> draws. A gate that has never failed on purpose has never shown that it can fail, and a green from a check that exercises nothing is the mock mirage. A checker applies its own rules to itself, or it asks of the code what it does not ask of its own source. And above every verifier sits an anchor that cannot be verified, only disclosed, because a gate cannot prove itself; a verdict is the value <cite>a verdict</cite> types, and one whose surfaces moved beneath it loses its standing, as <cite>lost standing</cite> draws. The check comes first is the same proof taken at authoring time.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Trust a check only after the proof the check comes first requires, and keep both cases as tests. Test every detector adversarially with the inputs that fool a shallow match, a look-alike character, a pattern inside a comment, a shape without the structure. Run the governance tooling through the same gate it enforces. Disclose the anchor everything else rests on, and when a gate goes green after a structural change, confirm it still loads what it claims to load.",
                    boundary:
                        "The anchor is the boundary. A verifier trusts that the runtime runs, that the filesystem reads, that a command executes and that tool output arrives, and it says so rather than pretending to verify them. Above the anchor everything is verified; the anchor itself is disclosed.",
                    cause: "A check's own green is the only evidence of its health, and green is also what a broken check produces.",
                    decision:
                        "Trust a verifier only after a positive control, a planted failure and an adversarial test.",
                    failureMode:
                        "A gate is green for a year. Someone reads its source and finds it has matched nothing since a refactor changed the file suffix it looked for.",
                    kind: "lesson",
                    principle: "A positive control verifies the verifier before anyone believes what it says.",
                    problem: "A green check is evidence of nothing until you know the check can go red.",
                    validation:
                        "For each check, find the planted case that turned it red and the real case that turned it green. A check missing either one is unverified.",
                },
                {
                    kind: "text",
                    text: "The failure the anchor guards against is concrete. A loader that discovers checks by a name pattern reports success while loading none of them if the pattern no longer matches what is on disk. Every step passes. Nothing is checked. So a green run after a structural change is followed by one question: does the run still load what it claims to load, with the generated index naming the checks and the loader's own count as the evidence. A harness that cannot fail is the same class: a stub standing in for an absent environment must answer only that environment, because a permissive stub that also absorbs the subject's own missing symbols converts every defect into a silent success.",
                },
                {
                    kind: "text",
                    text: "A verifier that audits claims audits itself last, and an overclaim in its own contract drops its confidence below the threshold, so a run below the threshold is not a clearance. Agents as executed contracts shows how that self-audit runs and why a verifier binds to one phase at a time.",
                },
                {
                    kind: "text",
                    text: "A verdict carries a standing beside its value. Every surface a run reads is stamped when it is read and re-stamped at the end, optimistic locking over a read set, and a run whose read set moved beneath it names the surfaces that moved and is not authoritative. The verdict is untouched, a pass stays a pass, and what is withdrawn is its standing to be quoted, because the report then describes an interleaving rather than a state. Holding a write barrier across a read would be the wrong repair, pessimistic locking that serialises every verification against every write to answer a question about the past. As a type, the standing is derived from whether the moved set is empty rather than written by the run. The set the run reached is named, so a green is readable as coverage over that set and silence over the rest, and the surfaces the run itself healed are named apart from the ones that moved, because a run's own repairs are not contention. A clearance is then one function over the record: a pass whose standing is authoritative, and any other combination is a value without the standing to be quoted.",
                },
                { code: VERDICT_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "a verdict" },
                { caption: "earning trust", kind: "mermaid", text: CONTROL_DIAGRAM },
                { caption: "lost standing", kind: "mermaid", text: STANDING_DIAGRAM },
            ],
            title: "Positive control first",
        },
    ],
    title: "Verify the verifier",
};

const REPORT_SECTION: Section = {
    icon: REPORT_SECTION_ICON,
    id: REPORT_SECTION_ID,
    intro: "A verification runs once per state of the tree, and its first output is the answer; reproducibility is what a second run would test, and a differing second run is a finding rather than a retry. You read the output whole and never search it for the line you hoped to see. The run writes the report on every exit, so nobody mistakes a present report for a passing one. Validation gates on the grammar page hold an instruction's claims to the same standard: checkable, with evidence.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Run the gate once. Write its full output to a file. Read the file whole. Fix what it names. Change the tree. Only then run again, and never re-run to see if the answer changes. Read a report's scope before its verdict, because a clearance from a check that cannot see the whole surface is worse than a visible gap.",
                    boundary:
                        "A run is warranted when the tree has changed, and then the report is history and the run is the measurement. The tell of the misuse is a second invocation whose only difference is the filter.",
                    cause: "A second run of the same state either repeats the answer or reveals non-determinism, and both are already findings from the first run.",
                    decision: "Change the tree between runs rather than the filter between reads.",
                    failureMode:
                        "The check fails, gets re-run twice, passes on the third try, and the flake ships with the change: flaky test normalization in one sentence.",
                    kind: "lesson",
                    principle: "One run per state, output read whole, report written on every exit path.",
                    problem: "Re-running a check until it passes turns a verifier into a slot machine.",
                    validation:
                        "Count the runs per tree state in a session. Anything above one is either a flake you should have filed or an answer you did not like.",
                },
                {
                    kind: "text",
                    text: "Reading whole is a rule about structure, not about diligence. A slice of a report answers only the question the reader already thought to ask, and the reason a check writes a finding is to raise something the reader had not thought of. A search is worse than an offset: an offset shows what was skipped, and a search silently omits everything that did not match. The same holds for a file and for a coordination surface, and the oversize error a read returns is the cue to read in parts until the whole has been read, never the cue to sample.",
                },
                {
                    kind: "text",
                    text: "A count is evidence of coverage only over the surface the scan reaches. A report therefore carries its derivations and not only its verdict: what it reached, what it excluded and why, so a green is readable as coverage rather than as silence. A negative result inherits the scope of the query that produced it and carries no evidence of its own, so before reporting that something does not exist the measurement is re-run one scope wider and taken over every surface where the thing could be declared.",
                },
            ],
            title: "One run, read whole",
        },
    ],
    title: "A report, not a checkbox",
};

const UNKNOWN_SECTION: Section = {
    icon: UNKNOWN_SECTION_ICON,
    id: UNKNOWN_SECTION_ID,
    intro: "A verdict has three values and the third is the one a percentage hides, as <cite>three verdicts</cite> draws. A surface no test touches has not passed; it is unknown, and unknown never rounds up.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Map the surfaces a unit can fail in before writing its tests, the catalogue what can drift, seen through how it drifts projects onto correctness: each surface with its failure modes, its technique, its predicate and its evidence source. Report the surfaces that are still unknown as unknown, never as passed, and treat an evidence set that is empty as a verdict of unknown rather than as an absence of failure.",
                    cause: "A percentage counts lines executed, and a line can execute while no claim about it gets checked.",
                    decision: "Measure coverage as the surfaces a unit can fail in, not as a percentage of lines.",
                    failureMode:
                        "Coverage is high, the failure that ships lives in a case the test suite never imagined, and the number never moved.",
                    kind: "lesson",
                    principle:
                        "No evidence yields unknown, never pass. A verdict is pass or fail only against a non-empty evidence set.",
                    problem:
                        "Coverage pursued by intuition and reported as a percentage never walks the space a system can fail in.",
                    validation:
                        "For a unit, name a failure surface the tests do not touch. If you can, coverage is not complete, whatever the percentage says.",
                },
                { caption: "three verdicts", kind: "mermaid", text: VERDICT_DIAGRAM },
            ],
            title: "Three verdicts, not two",
        },
    ],
    title: "Unknown is not pass",
};

export const EVIDENCE_SECTIONS: readonly Section[] = [
    APPEARANCE_SECTION,
    VERIFIER_SECTION,
    REPORT_SECTION,
    UNKNOWN_SECTION,
];