configuration/strings/template.strings.ts

configuration/strings/template.strings.ts is a file in Bane's Lab Site. 61 lines of code and 7 definitions.

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: "This section covers the template and how an instance is raised from it. A template record has four parts, 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, as shown in <cite>template record</cite>. <cite>template and sibling</cite> shows how a template differs from a sibling instance. Raising an instance is a resolution in which 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. <cite>resolution</cite> lists the three outcomes. 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:
                        "In practice, a template is written the second time a shape occurs, before the second instance is written, in the order shown in <cite>second instance</cite>. It declares its type, names every slot with whether it is required and, where the values form a closed set, that set, and it names the constraints every instance must satisfy so a check can read them. The body keeps only what every instance shares, with every varying value as a slot. Each new instance is raised by resolving the slots, and an instance whose resolution reports an unresolved slot or a violation is refused.",
                    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:
                        "Shared structure is extracted once a pattern repeats, rather than copied from an earlier example.",
                    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:
                        "For this reason what every instance must share is stated once, where a tool can hold each new one to it.",
                    problem: "An instance derived from a sibling inherits that sibling's accidents as a contract.",
                    validation:
                        "To check this, 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 the template with one slot missing, and 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 its subject and filled by the adapter, so one template works 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, so it names no model, no path and no tool, for the reasons described in semantic operations. 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",
};