configuration/strings/invocation.strings.ts
configuration/strings/invocation.strings.ts is a file in Bane's Lab Site. 60 lines of code and 6 definitions.
import { GRAMMAR_VALIDATION_TAB, INVOCATION_SECTION_ID, LIMITATION_SECTION_ID } from "#core/ids/grammar.ids";
import { GRAMMAR_PAGE } from "#core/ids/page.ids";
import { INVOCATION_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { PAG_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";
import { tabLink } from "#core/assets/link.assets";
const OPERATION_SAMPLE =
'# SEMANTIC OPERATION BOUNDARY · a node states WHAT as an operation; an adapter decides HOW\n\n# discover, read, search, analyze · operations against a tree that produce values\nDISCOVER_RESOURCES "<pattern>" INTO <resources>\nREAD_RESOURCE <resource> INTO <content>\nSEARCH_CONTENT <content> FOR <term> INTO <matches>\nANALYZE_CONTENT <content> AGAINST <criteria> INTO <findings>\nEXTRACT_FACTS <fields> FROM <content> INTO <facts>\nCALCULATE_METRIC <measure> FROM <facts> INTO <value>\n\n# compose, validate, persist · operations that leave an artifact\nCOMPOSE_ARTIFACT <artifact> FROM <facts> USING <shape>\nVALIDATE_ARTIFACT <artifact> AGAINST <schema>\nPERSIST_ARTIFACT <artifact> TO <destination>\n\n# execute, decide, report · effects outside the tree and on other parties\nEXECUTE_TOOL <command> WITH timeout: <bound> INTO <result>\nREQUEST_DECISION <party> WITH options: [<a>, <b>] INTO <choice>\nREPORT_RESULT <artifact> TO <the parties whose next work it creates>';
const BINDING_SAMPLE =
"# the document names an operation and a slot · one adapter per harness resolves both, outside the document\nREAD_RESOURCE {project.governance_policy} INTO <policy>\nEXECUTE_TOOL {toolchain.verify_command} INTO <verdict>\n\nadapter:\n DISCOVER_RESOURCES → <the harness's discovery tool>\n READ_RESOURCE → <the harness's read tool>\n SEARCH_CONTENT → <the harness's search tool>\n EXECUTE_TOOL → <the harness's shell>\n PERSIST_ARTIFACT → <the harness's write tool>\n REQUEST_DECISION → <the harness's question surface, or ABSENT for a bounded reader>\n {project.governance_policy} → <the path in this tree>\n {toolchain.verify_command} → <the command in this tree, or ABSENT>";
const FORMS_SAMPLE =
'READ_RESOURCE <resource> # the operation and its target\nREAD_RESOURCE <resource> INTO <parsed> # bound to a name the next line reads\nSEARCH_CONTENT <scope> FOR <term> WITH glob: "*.md" # named parameters\nEXECUTE_TOOL <command> → <result> # the arrow is the same binding';
const BINDING_DIAGRAM =
'flowchart TB\n doc["The document · semantic operations and {slots}"]\n adapter["One adapter per harness"]\n harnessA["Harness A · its read tool, its shell, its question surface"]\n harnessB["Harness B · different tools, same document"]\n absent["A slot with no analogue · declared ABSENT, the branch does not run"]\n doc --> adapter\n adapter --> harnessA\n adapter --> harnessB\n adapter -. no analogue .-> absent';
const EFFECT_DIAGRAM =
'flowchart LR\n op["Operation · what happens"]\n target["Target · what it acts on"]\n params["WITH · named parameters"]\n result["INTO or arrow · where the result lands"]\n addressable["An effect the adapter can perform and the next line can read"]\n op --> target --> params --> result --> addressable';
export const INVOCATION_SECTION: Section = {
icon: INVOCATION_SECTION_ICON,
id: INVOCATION_SECTION_ID,
intro: "Every external effect in a document is a named semantic operation, with explicit parameters and an explicit binding for its result; <cite>invocation parts</cite> names those parts, and <cite>invocation forms</cite> writes them four ways. The operation says what happens, and <cite>the operations</cite> groups the operations by the kind of effect. An adapter outside the document, one per harness, decides how the effect is carried out, which is the split shown in <cite>document and adapter</cite> and <cite>one adapter per harness</cite>. An invocation is the act stage of the loop, and it yields a procedure.",
subsections: [
{
blocks: [
{
application:
"In practice, every effect is named with a semantic operation and given a target, its parameters are passed through a named clause, and its result is bound to a name the next line can read. A location or a command is referred to through a slot the adapter resolves, never through a literal path, and the harness's own tool names, configuration files and features stay out of the document.",
boundary:
"A document written for exactly one throwaway session may name whatever it likes, because nothing will port it. The discipline is for a document that will be walked again, by another party, or under another harness.",
cause: "What one harness calls its tools changes when that harness changes, so any text written against those calls ages with it.",
decision:
"The document is separated from the harness at the operation, with one adapter per harness, rather than one document being written per harness.",
failureMode:
"A library of documents names one harness's tools throughout, the harness changes its tool set, and every document breaks at once, which is vendor lock-in leakage with nothing in any document to explain it.",
kind: "lesson",
principle:
"For this reason what an effect means is fixed in the text, and how it runs is decided outside it.",
problem:
"An effect described in prose is not addressable by any adapter, and an effect named by one harness's tool is hardcoded configuration that only that harness can address.",
validation:
"To check this, rename the harness under the document and hand it to a different model. Where a line fails, it carried a tool name or a path where an operation or a slot belonged, and the fix belongs in the adapter.",
},
{
kind: "text",
text: "The operations fall into three groups by the kind of effect: those that act on a tree and produce values, those that leave an artifact in it, and those that reach outside it or address another party. Each operation carries a semantic contract, so a document relies on the contract rather than on what a particular tool happens to do.",
},
{
kind: "text",
text: `Portability follows from this boundary. Operations and slots in the document are configuration externalization applied to an instruction, and one adapter per harness is the adapter pattern. A slot with no counterpart in a harness resolves as absent, as described under <a href="${tabLink(GRAMMAR_PAGE, GRAMMAR_VALIDATION_TAB, LIMITATION_SECTION_ID)}">limits</a>. A decision request is the clearest case: a participant has a question surface and a bounded reader does not, so the same operation resolves for one and is absent for the other, while the document stays unchanged. The model a document runs under is always a slot, because choosing the model belongs to the harness.`,
},
{ code: OPERATION_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "the operations" },
{ code: BINDING_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "document and adapter" },
{ code: FORMS_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "invocation forms" },
{ caption: "one adapter per harness", kind: "mermaid", text: BINDING_DIAGRAM },
{ caption: "invocation parts", kind: "mermaid", text: EFFECT_DIAGRAM },
],
title: "Operations, not tools",
},
],
title: "Semantic operations",
};