import { INVARIANT_SECTION_ICON } from "#configuration/icons/coordination.icons";
import { INVARIANT_SECTION_ID } from "#core/ids/coordination.ids";
import type { Section } from "#types/document.types";
import { TYPESCRIPT_LANGUAGE } from "#configuration/constants/code.constants";
import { nodeLink as node } from "#domain/converters/link.converter";

const LIFETIME_SHAPE =
    'export const RETENTION = ["accumulating", "current-truth", "discharged", "computed"] as const;\nexport const MUTABILITY = ["append-only", "owner-rewritable", "frozen"] as const;\nexport const REMOVAL = ["none", "author", "handler", "producer"] as const;\n\nexport interface Lifetime {\n    readonly retention: (typeof RETENTION)[number];\n    readonly mutability: (typeof MUTABILITY)[number];\n    readonly removal: (typeof REMOVAL)[number];\n}\n\nexport interface LifetimeRegion {\n    readonly name: string;\n    readonly span: "item" | "field" | "row" | "column";\n    readonly lifetime: Lifetime;\n    readonly why: string;\n}\n\nexport interface LifetimeDeclaration {\n    readonly declared: Readonly<Record<SurfaceKey, Lifetime>>;\n    readonly regions: Readonly<Record<SurfaceKey, readonly LifetimeRegion[]>>;\n    readonly seeds: Readonly<Record<SurfaceKey, SurfaceKey>>;\n}\n\nexport const lifetime: LifetimeDeclaration = {\n    declared: {\n        "<swept-surface>": { retention: "current-truth", mutability: "owner-rewritable", removal: "handler" },\n        "<accumulating-surface>": { retention: "accumulating", mutability: "frozen", removal: "none" },\n        "<generated-surface>": { retention: "computed", mutability: "frozen", removal: "producer" },\n    },\n    regions: {\n        "<rule-surface>": [{ name: "<region>", span: "field", lifetime: { retention: "accumulating", mutability: "owner-rewritable", removal: "author" }, why: "<why this span differs from its file>" }],\n    },\n    seeds: { "<template>": "<swept-surface>" },\n};';

const SLOTS_DIAGRAM =
    'flowchart TB\n    invariant["A stated invariant"]\n    property["The property · in a form that could be false"]\n    set["The set it quantifies over · never a verdict beyond its range"]\n    parties["The parties it binds · delivered in a surface they receive"]\n    objector["The objector · a check, a refusal, a comparison, a party that would notice"]\n    unheld["Or stated as unheld · and the derivations above it marked"]\n    invariant --> property\n    invariant --> set\n    invariant --> parties\n    invariant --> objector\n    invariant -. no objector .-> unheld';

const LIFETIME_DIAGRAM =
    'flowchart TB\n    surface["A surface\'s lifetime"]\n    retention["Retention · what ends a piece of content"]\n    mutability["Mutability · whether a landed statement may be rewritten, and by whom"]\n    removal["Removal authority · who may take content out"]\n    word["One word · true of every surface and sufficient for none"]\n    surface --> retention\n    surface --> mutability\n    surface --> removal\n    surface -. collapsed to .-> word';

const ARITY_DIAGRAM =
    'flowchart TB\n    property{"Is the property a relation between two states?"}\n    single["A single-state check · presence, shape, membership, conformance"]\n    two["Two readings · retain the prior state, record the set it was taken over, compare"]\n    blind["A stricter single-state check · the same blind spot, more demanding"]\n    third["Three results · unchanged, shortened, not comparable"]\n    property -- no --> single\n    property -- yes --> two --> third\n    property -. the tempting repair .-> blind';

const INVARIANT_SECTION: Section = {
    icon: INVARIANT_SECTION_ICON,
    id: INVARIANT_SECTION_ID,
    intro: "A topology relies on invariants, and one it relies on without stating is indistinguishable from a property a reader happened to infer; design by contract for a collaboration, where the preconditions and postconditions are the parties'. The test is not whether the invariant is true. It is whether anything would disagree if it stopped being. A property that holds today with no dissenting mechanism is held by circumstance, and its first violation is silent. A stated invariant fills the slots <cite>four slots</cite> draws, a lifetime is the three axes <cite>three axes</cite> draws and <cite>a lifetime declaration</cite> types, and a relation between two states needs the two readings <cite>two readings</cite> draws. Orchestration invariants on the grammar page carries the same four slots for a declared workflow.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "State an invariant with four things: the property in a form that could be false, the set it quantifies over, the parties it binds, and the thing that would object if it stopped holding. Deliver it in a surface the bound parties receive, because a mechanism that must honour an invariant is the hardest consumer to remember, being the only one that cannot ask. Where no objector exists, state the invariant as unheld and mark every derivation that rests on it.",
                    boundary:
                        "Stating an invariant does not make it enforced. A statement is a claim about the topology and a check is a mechanism over artifacts, and where one exists without the other the honest form names which. An invariant held by a tool holds exactly as long as every party uses the tool, and a hand path around it is invisible to everything.",
                    cause: "Nothing objects when an unstated invariant stops holding, so its first violation is silent.",
                    decision: "Name the objector before relying on the property, rather than the property alone.",
                    failureMode:
                        "Two documents state the opposite of one invariant, every mechanism implements its own statement faithfully, nothing reports a defect, and the contradiction exists only in a reader who holds both at once.",
                    kind: "lesson",
                    principle:
                        "An invariant is stated with its property, its set, its parties and its objector, or it is stated as unheld.",
                    problem:
                        "An unstated invariant is not a documentation gap but a defect in every claim standing on it.",
                    validation:
                        "For an invariant the design relies on, name what would disagree if it stopped holding. If nothing would, the invariant is held by circumstance and its first violation will be silent.",
                },
                {
                    kind: "text",
                    text: "The contradicted invariant is the failure no check can see, so the unit of the check is the set of statements rather than one statement. An invariant is restated wherever a party needs it, which delivery demands, and every restatement is a copy that can disagree, so adding a statement adds an obligation to re-derive the set whenever the invariant changes, ordered by how often each copy is delivered.",
                },
                { caption: "four slots", kind: "mermaid", text: SLOTS_DIAGRAM },
            ],
            title: "Property, set, parties, objector",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "A lifetime is three independent axes, and one word makes the rest unstatable; immutability, for instance, is one value on one of them. Retention says what ends a piece of content. Mutability says whether a landed statement may be rewritten and by whom. Removal authority says who may take content out. No two are derivable from each other, a topology running more than one kind of surface exhibits surfaces differing on each axis independently, and the axis a one-word form drops first is removal authority, because a reader assumes it follows from retention. It does not: keeping content and forbidding its removal are separate claims, and a mechanism implementing the first faithfully can perform the second. Each axis takes a value from a closed set, which is what makes the declaration an operand rather than a sentence.",
                },
                { caption: "three axes", kind: "mermaid", text: LIFETIME_DIAGRAM },
                { code: LIFETIME_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "a lifetime declaration" },
            ],
            title: "A lifetime is three axes",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: `A property that is a relation between two states is not enforceable by any check evaluated against one. Presence, shape, membership and conformance are decided from a single reading, the ${node("ana-structural", "structural")} lens. That content may grow and not shrink, be corrected and not removed, advance and not retreat, is a happens-before relationship, the ${node("ana-temporal", "temporal")} lens, and it is decided only from two. A required section is enforced from empty to full and silent from full to empty, and a stricter single-state check has the identical blind spot. The repair is an arity change: retain the prior state, record the set it was taken over, and compare, with three results rather than two, because a comparison across differing sets refuses rather than computing, and a false accusation is the direction a refusal acts on.`,
                },
                { caption: "two readings", kind: "mermaid", text: ARITY_DIAGRAM },
            ],
            title: "Two states need two readings",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "Declared as data, a lifetime looks like this. Each axis is a literal tuple and the field type is derived from it, so a value outside the closed set fails to compile rather than resolving as a fourth state nobody declared. A surface is a key and its lifetime is one record over the three axes, so a check joins on the axis name and reads the value. A region declares only where it differs from its file, naming the span it covers, the lifetime it carries and why, which is the bound that keeps the declaration countable.",
                },
                {
                    kind: "text",
                    text: "A seed names which live surface a template raises, so the template declares a lifetime for an instance rather than for itself, and a seed pointing at an undeclared surface is a compile error rather than a citation that resolves to nothing. The values are not ordered and none is a default: a surface that declares nothing is undeclared, which is a different state from any value, and collapsing the two makes an unmeasured surface indistinguishable from a measured one.",
                },
            ],
            title: "Declared as data",
        },
    ],
    title: "Stating an invariant",
};

export const INVARIANT_FRAGMENT_SECTIONS: readonly Section[] = [INVARIANT_SECTION];