import { PAG_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";
import { WRITING_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { WRITING_SECTION_ID } from "#core/ids/grammar.ids";

const CONSTRAINT_SAMPLE =
    "# CROSS-NODE INVARIANTS · hold for every node, read after the nodes they bind · each a record with four slots\nINVARIANT read-before-write: a surface is read whole before anything is persisted to it over: every persisting node binds: the reader objector: [check] a witness read precedes PERSIST_ARTIFACT\nINVARIANT validate-at-boundary: an input is validated at every node boundary over: every node binds: the reader objector: [check] VALIDATE_ARTIFACT ran on the input at the gate\nINVARIANT prior-output-only: a node reads only the prior node's output over: every node binds: the reader objector: [check] input names NODE n-1 or a slot\nINVARIANT no-silent-blocker: a blocker stops the run until a decision is requested over: every node binds: the reader objector: [check] result routes unknown to BLOCKED\nINVARIANT source-untouched: <source> is never modified in place over: <source> binds: the reader objector: none\n\n# scoped · a property that holds only inside a named context is stated with that context in its set\nINVARIANT encrypt-sensitive: every sensitive field is encrypted before it leaves the node over: nodes handling <sensitive-data> binds: the reader objector: [check] no plain-text field in the persisted artifact\nINVARIANT audit-access: every access to <sensitive-data> is recorded over: nodes handling <sensitive-data> binds: the reader objector: [check] one audit entry per access\nINVARIANT bounded-retention: <data> is not retained past <retention-period> over: persisted <data> binds: the reader objector: none";

const CONTRAST_SAMPLE =
    "# a rule the model can quote back · and a reviewer can check against a line\nALWAYS handle errors properly\nINVARIANT wrapped-io: every <file-operation> runs inside TRY/CATCH over: file operations binds: the reader objector: [check] no bare file operation in the transform\n\nNEVER do bad things\nINVARIANT inside-the-root: nothing is persisted outside <workspace-root> over: every PERSIST_ARTIFACT binds: the reader objector: [check] every destination under the root\n\nALWAYS be careful with data\nINVARIANT validated-first: <data> is validated against <schema> before it is processed over: every node reading <data> binds: the reader objector: [check] VALIDATE_ARTIFACT precedes the first use\n\nNEVER modify anything\nINVARIANT read-only-zone: no file in <read-only-zone> is modified over: <read-only-zone> binds: the reader objector: [check] a witness read of the zone after the run";

const WORKED_SAMPLE =
    '---\nname: <processor-name>\ntype: WORKFLOW\nversion: 1.0.0\n---\n\nTHIS WORKFLOW EXECUTES validation and transformation of <records>\n\n%% META %%:\n    objective: "An <output> whose entry count matches the conforming input"\n    jurisdiction: <source> and <output> | external: every other file\n    recursion_limit: 2\n\nON ERROR <write-failed>:\nTRY:\n    RENAME <file> TO <file>.bak\n    PERSIST_ARTIFACT <content> TO <file>\n    DELETE <file>.bak\nCATCH:\n    RENAME <file>.bak TO <file>\n\n# NODE 1 — INPUT VALIDATION   [epistemic · analysis · logic · yields: boolean]\n@genesis: existence\nCONTRACT:\n  input:     <source>\n  transform: READ_RESOURCE <source> INTO <input>; FOR EACH <row> IN <input>.<rows>: VALIDATE_ARTIFACT <row> AGAINST <schema>; IF <row>.<conforms>: APPEND <row> TO <valid> ELSE: REPORT_RESULT "<which row, which field>"\n  output:    <valid>\nHANDOFF GATE:\n  [check] <input> read (evidence: the read returned rows)\n  [check] every <row> validated (evidence: one verdict per row) over: <input>.<rows> measured: <validated> / <rows>\n  [check] every non-conforming <row> reported with its field (evidence: the report names a field per rejection)\n  result: pass -> NODE 2 | unread -> REPAIR (owner: NODE 1) | unknown -> BLOCKED\n\n# NODE 2 — TRANSFORMATION     [epistemic · formalisation · computation · yields: procedure]\n@genesis: transformation\nCONTRACT:\n  input:     <valid> from NODE 1\n  transform: FOR EACH <row> IN <valid>: COMPOSE_ARTIFACT <entry> FROM <row> USING <mapping>; APPEND <entry> TO <shaped>\n  preserves: the source row of every entry\n  output:    <shaped>\nHANDOFF GATE:\n  [check] one <entry> per <row> in <valid> (evidence: the two counts match) over: <valid> measured: <shaped> / <rows>\n  [check] every <entry> conforms to <mapping> (evidence: VALIDATE_ARTIFACT passed on each)\n  [check] <valid> unchanged (evidence: a witness read after the transform)\n  result: pass -> NODE 3 | mismatch -> REPAIR (owner: NODE 2) | unknown -> BLOCKED\n\n# NODE 3 — OUTPUT             [evaluative · representation · information-theory · yields: artifact]\n@genesis: emergence\nCONTRACT:\n  input:     <shaped> from NODE 2\n  transform: PERSIST_ARTIFACT <shaped> TO <output>\n  output:    <output>\n  freshness: fingerprint(<shaped>) + fingerprint(this document)\nHANDOFF GATE:\n  [check] <output> persisted (evidence: a read of <output> returns it)\n  [check] entry count of <output> matches <shaped> (evidence: the two counts match) over: <shaped> measured: <persisted> / <entries>\n  [check] <source> unchanged (evidence: a witness read)\n  refuse: <output> changed since it was read before PERSIST_ARTIFACT\n  result: pass -> TERMINATE | loss -> REPAIR (owner: NODE 3) | unknown -> BLOCKED\n\n# CROSS-NODE INVARIANTS\nINVARIANT validate-before-transform: every row is validated before any transform reads it over: every node binds: the reader objector: [check] every <row> validated at NODE 1\nINVARIANT reject-with-field: a rejected <row> is reported with its field over: rejected rows binds: the reader objector: [check] the report names a field per rejection at NODE 1\nINVARIANT source-untouched: <source> is never modified over: <source> binds: the reader objector: [check] <source> unchanged at NODE 3\nINVARIANT non-empty-input: the run does not proceed with zero conforming rows over: every run binds: the reader objector: [check] every <row> validated at NODE 1 over a non-empty set\n\nREPORT:\n  subject: NODE 3\n  verdict: pass | fail | unknown\n  domain: declared <rows> measured <validated>\n  populations: conforming <n>, rejected <n>, persisted <n>\n  completion: saturated <bool> complete <bool> verified <bool>';

const CONSTRAINT_DIAGRAM =
    'flowchart TB\n    rule["A rule"]\n    exhort["An exhortation · be careful, handle properly"]\n    judged["Judged by the model, differently each run"]\n    specific["A record · property, set, parties, objector"]\n    checkable["Checked by the objector, or declared unwatched"]\n    quoted["Quoted back by the model when it applies"]\n    rule --> exhort --> judged\n    rule --> specific --> checkable\n    specific --> quoted';

const SCOPE_DIAGRAM =
    'flowchart LR\n    property["The property · could be false"]\n    set["over · the set it ranges over, the whole document or one context"]\n    parties["binds · who must receive it"]\n    objector["objector · what would disagree, or none"]\n    property --> set --> parties --> objector';

export const WRITING_SECTION: Section = {
    icon: WRITING_SECTION_ICON,
    id: WRITING_SECTION_ID,
    intro: "A constraint states a boundary in a form the model can quote back and a reviewer can check against a line: a property that could be false, the set it ranges over, the parties it binds, and the objector that would disagree if it stopped holding. Those are the four slots <cite>four slots</cite> draws and <cite>invariant records</cite> fills. A rule that holds everywhere names every node as its set; a rule that holds inside a context names that context. The invariant block is the constrain stage of the loop: it decides what is admissible, and it yields a boolean over the work rather than an opinion about it, closing the document as <cite>worked document</cite> shows. A rule written as encouragement is judged rather than checked, the fate <cite>exhortation or record</cite> traces. A rule written as a bullet under a head carries no set and no objector, so nothing can say when it was broken, and <cite>exhortation rewritten</cite> is the repair.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "State each constraint as an invariant record: a name, a property with a verb and its operand, the set it quantifies over, the parties it binds, and the objector, a gate check or none. Scope a rule that holds only in a context by naming the context in its set rather than nesting a block. Write each so a reviewer can point at a directive and say it broke this one, and place the block after the last node.",
                    boundary:
                        "A constraint the model cannot observe from inside the document, such as a rule about its own confidence, is not checkable by anyone and belongs under limits rather than in an invariant record.",
                    cause: "A model completes an exhortation with whatever careful looks like in its training, and a specific prohibition with the thing it names; a record with a named objector is the only form in which a reviewer and a check read the same rule.",
                    decision:
                        "Trade the reach of a broad exhortation for the checkability of a narrow record, one violating directive per rule and one objector per record.",
                    failureMode:
                        "A document says handle errors properly, the model wraps some operations and not others, and the reviewer cannot say the rule was broken because the rule never said what handling was.",
                    kind: "lesson",
                    principle: "A behavioural boundary is a checkable record with its objector, not guidance.",
                    problem:
                        "A rule stated as an exhortation binds nothing, because nobody can say when it was broken.",
                    validation:
                        "For each constraint, write the one directive that would violate it and name the check that would notice. A constraint with no violating directive is an exhortation; one with no objector is declared debt, and the record says so with none.",
                },
                {
                    kind: "text",
                    text: "Scope is what keeps a constraint set small: a rule that holds everywhere is stated once with every node as its set, and a rule that holds somewhere names where. The rewrite from exhortation to record is the same move every time: name the operation, name the operand, drop the adverb, and say what would object. That is policy as code, and it is what lets a gate's check cite an invariant by name rather than restate it, as orchestration invariants derives.",
                },
                {
                    kind: "text",
                    text: "Invariants close a document rather than open it because they are read against the work they bind. A recovery block sits near the top because recovery is a mechanism rather than a rule.",
                },
                { code: CONSTRAINT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "invariant records" },
                { code: CONTRAST_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "exhortation rewritten" },
                { code: WORKED_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "worked document" },
                { caption: "exhortation or record", kind: "mermaid", text: CONSTRAINT_DIAGRAM },
                { caption: "four slots", kind: "mermaid", text: SCOPE_DIAGRAM },
            ],
            title: "Rules the model can quote",
        },
    ],
    title: "Writing constraints",
};