import { PAG_LANGUAGE, TEXT_LANGUAGE } from "#configuration/constants/code.constants";
import { templateBodyOf, templateConstraintsOf } from "#core/converters/grammar.converter";
import type { Section } from "#types/document.types";
import { TEMPLATE_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { TEMPLATE_SECTION_ID } from "#core/ids/grammar.ids";

const CONSTRAINT_INDENT = "\n    - ";

const RECORD_SHAPE = `template:\n  type:        WORKFLOW                       # a declared document type · nothing else\n  title:       <what the family is for>\n  slots:\n    - name:        {WORKFLOW_NAME}             # the value an instance supplies\n      description: <what the slot holds>\n      required:    true\n      kind:        string\n    - name:        {project.governance_policy}   # a host fact · resolved by the adapter, never typed\n      required:    true\n    - name:        {limits.max_lines}            # a bound · resolved from the host's limits\n      required:    false\n    - name:        {scope}\n      required:    true\n      enum:        [<investigate>, <action>]     # a closed set · a value outside it is a violation\n  constraints:                                  # what every instance must satisfy · named, checkable${
    CONSTRAINT_INDENT
}${templateConstraintsOf("WORKFLOW").join(
    CONSTRAINT_INDENT,
)}\n  body: |\n    <the document, with every slot as {name}>`;

const WORKFLOW_TEMPLATE = templateBodyOf("WORKFLOW");

const RESOLUTION_SAMPLE =
    "resolve <template> WITH <the values an instance supplies>\n\n  substituted   every {name} the instance supplied, replaced in the body\n  unresolved    [{OUTPUT_TARGET}]                        # still in the body · the instance is not ready\n  violations    [missing_required_slot:{OBJECTIVE},       # a required slot with no value\n                 enum_violation:{scope}]                  # a value outside the slot's closed set\n\n# an instance with a non-empty unresolved or violations list is not raised · nothing guesses a value";

const CONTRACT_DIAGRAM =
    'flowchart TB\n    template["A template record · type, slots, constraints, body"]\n    raised["An instance · raised by resolving every slot"]\n    check["A check · reads the constraints and the slot declarations"]\n    sibling["A sibling instance"]\n    copied["An instance copied from the sibling · inherits its accidents"]\n    template --> raised\n    template --> check\n    sibling -. the tempting path .-> copied';

const SECOND_DIAGRAM =
    'flowchart LR\n    one["One instance · an artifact"]\n    two["A second · the invariant half is now visible"]\n    template["The template is written before the second is"]\n    later["Every later instance is raised from it"]\n    one --> two --> template --> later';

export const TEMPLATE_SECTION: Section = {
    icon: TEMPLATE_SECTION_ICON,
    id: TEMPLATE_SECTION_ID,
    intro: "A template is a record with four parts, as <cite>template record</cite> shows: a declared document type, the slots an instance fills, the constraints every instance must satisfy, and a body in which every slot appears by name. It carries the contract of a shape and never one instance's content, which is what <cite>template and sibling</cite> contrasts. Raising an instance is a resolution: each slot is substituted, a slot left unresolved is reported rather than guessed, and a value outside a slot's declared set is a violation, the three outcomes <cite>resolution</cite> lists. The record and <cite>workflow body</cite> are the grammar's own workflow template, read from its records rather than restated here.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Write a template the second time a shape occurs, before the second instance is written, as <cite>second instance</cite> orders it. Declare its type, name every slot with whether it is required and, where the values form a closed set, that set. Name the constraints every instance must satisfy so a check can read them. Keep in the body only what every instance shares, with every varying value as a slot. Raise each new instance by resolving the slots, and refuse an instance whose resolution reports an unresolved slot or a violation.",
                    boundary:
                        "A shape seen once has no template, because one instance cannot show which of its parts are invariant. A template raised from one instance is premature abstraction.",
                    cause: "A sibling carries one instance's choices and a template carries the constraint, and a reader copying a sibling cannot tell which is which.",
                    decision:
                        "Raise the second instance from a template written for it, rather than from the first instance.",
                    failureMode:
                        "Four parties produce four formats for one surface, each derived from a different sibling, and the check that later reads them derives its schema from a fifth.",
                    kind: "lesson",
                    principle:
                        "A template carries the contract, an instance resolves its slots, and a check reads the template.",
                    problem: "An instance derived from a sibling inherits that sibling's accidents as a contract.",
                    validation:
                        "Take a template and find a value in it that would be wrong for the next instance. That value is content rather than contract, and a slot is the repair. Then resolve it with one slot missing: a resolution that raises the instance anyway has guessed.",
                },
                {
                    kind: "text",
                    text: "The slots fall into two kinds by who supplies the value. An instance slot is what this document is for, supplied when it is raised. A host slot is a fact about the tree the document will be walked in, namespaced by what it is a fact about, and resolved by the adapter rather than typed into an instance, which is what keeps one template raisable in any tree.",
                },
                {
                    kind: "text",
                    text: "The constraints are the family's acceptance criteria, and a check over an instance reads them from the template, as the drop-in describes. What the template excludes is as deliberate as what it carries: no model, no path, no tool, for the reasons semantic operations gives. A correction lands in the template and reaches every later instance, never in the instance where only its author would see it.",
                },
                { code: RECORD_SHAPE, kind: "code", language: TEXT_LANGUAGE, title: "template record" },
                { code: WORKFLOW_TEMPLATE, kind: "code", language: PAG_LANGUAGE, title: "workflow body" },
                { code: RESOLUTION_SAMPLE, kind: "code", language: TEXT_LANGUAGE, title: "resolution" },
                { caption: "template and sibling", kind: "mermaid", text: CONTRACT_DIAGRAM },
                { caption: "second instance", kind: "mermaid", text: SECOND_DIAGRAM },
            ],
            title: "Contract, not content",
        },
    ],
    title: "Core templates",
};